chore: release packages (#436)

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

.changeset/config.json

@@ -49,7 +49,6 @@
     "@esengine/material-editor",
     "@esengine/shader-editor",
     "@esengine/world-streaming-editor",
-    "@esengine/node-editor",
     "@esengine/sdk",
     "@esengine/worker-generator",
     "@esengine/engine"

.github/workflows/release-changesets.yml

@@ -57,8 +57,12 @@ jobs:
           pnpm --filter "@esengine/rpc" build
           pnpm --filter "@esengine/network" build
           pnpm --filter "@esengine/server" build
+          pnpm --filter "@esengine/database-drivers" build
+          pnpm --filter "@esengine/database" build
+          pnpm --filter "@esengine/transaction" build
           pnpm --filter "@esengine/cli" build
           pnpm --filter "create-esengine-server" build
+          pnpm --filter "@esengine/node-editor" build
 
       - name: Create Release Pull Request or Publish
         id: changesets

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/astro.config.mjs

@@ -267,6 +267,7 @@ export default defineConfig({
                 { label: '概述', slug: 'modules/network', translations: { en: 'Overview' } },
                 { label: '客户端', slug: 'modules/network/client', translations: { en: 'Client' } },
                 { label: '服务器', slug: 'modules/network/server', translations: { en: 'Server' } },
+                { label: 'HTTP 路由', slug: 'modules/network/http', translations: { en: 'HTTP Routing' } },
                 { label: '认证系统', slug: 'modules/network/auth', translations: { en: 'Authentication' } },
                 { label: '速率限制', slug: 'modules/network/rate-limit', translations: { en: 'Rate Limiting' } },
                 { label: '状态同步', slug: 'modules/network/sync', translations: { en: 'State Sync' } },
@@ -287,6 +288,25 @@ export default defineConfig({
                 { label: '分布式事务', slug: 'modules/transaction/distributed', translations: { en: 'Distributed' } },
               ],
             },
+            {
+              label: '数据库',
+              translations: { en: 'Database' },
+              items: [
+                { label: '概述', slug: 'modules/database', translations: { en: 'Overview' } },
+                { label: '仓储模式', slug: 'modules/database/repository', translations: { en: 'Repository' } },
+                { label: '用户仓储', slug: 'modules/database/user', translations: { en: 'User Repository' } },
+                { label: '查询构建器', slug: 'modules/database/query', translations: { en: 'Query Builder' } },
+              ],
+            },
+            {
+              label: '数据库驱动',
+              translations: { en: 'Database Drivers' },
+              items: [
+                { label: '概述', slug: 'modules/database-drivers', translations: { en: 'Overview' } },
+                { label: 'MongoDB', slug: 'modules/database-drivers/mongo', translations: { en: 'MongoDB' } },
+                { label: 'Redis', slug: 'modules/database-drivers/redis', translations: { en: 'Redis' } },
+              ],
+            },
             {
               label: '世界流式加载',
               translations: { en: 'World Streaming' },

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/behavior-tree/custom-actions.md

@@ -182,6 +182,70 @@ export class IsHealthLow implements INodeExecutor {
 }
 ```
 
+## Using Custom Executors in BehaviorTreeBuilder
+
+After defining a custom executor with `@NodeExecutorMetadata`, use the `.action()` method in the builder:
+
+```typescript
+import { BehaviorTreeBuilder, BehaviorTreeStarter } from '@esengine/behavior-tree';
+
+// Use custom executor in behavior tree
+const tree = BehaviorTreeBuilder.create('CombatAI')
+    .defineBlackboardVariable('health', 100)
+    .defineBlackboardVariable('target', null)
+    .selector('Root')
+        .sequence('AttackSequence')
+            // Use custom action - matches implementationType in decorator
+            .action('AttackAction', 'Attack', { damage: 25 })
+            .action('MoveToTarget', 'Chase')
+        .end()
+        .action('WaitAction', 'Idle', { duration: 1000 })
+    .end()
+    .build();
+
+// Start the behavior tree
+const entity = scene.createEntity('Enemy');
+BehaviorTreeStarter.start(entity, tree);
+```
+
+### Builder Methods for Custom Nodes
+
+| Method | Description |
+|--------|-------------|
+| `.action(type, name?, config?)` | Add custom action node |
+| `.condition(type, name?, config?)` | Add custom condition node |
+| `.executeAction(name)` | Use blackboard function `action_{name}` |
+| `.executeCondition(name)` | Use blackboard function `condition_{name}` |
+
+### Complete Example
+
+```typescript
+// 1. Define custom executor
+@NodeExecutorMetadata({
+    implementationType: 'AttackAction',
+    nodeType: NodeType.Action,
+    displayName: 'Attack',
+    category: 'Combat',
+    configSchema: {
+        damage: { type: 'number', default: 10, supportBinding: true }
+    }
+})
+class AttackAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const damage = BindingHelper.getValue<number>(context, 'damage', 10);
+        console.log(`Attacking with ${damage} damage!`);
+        return TaskStatus.Success;
+    }
+}
+
+// 2. Build and use
+const tree = BehaviorTreeBuilder.create('AI')
+    .selector('Root')
+        .action('AttackAction', 'Attack', { damage: 50 })
+    .end()
+    .build();
+```
+
 ## Registering Custom Executors
 
 Executors are auto-registered via the decorator. To manually register:

docs/src/content/docs/en/modules/blueprint/custom-nodes.md

@@ -28,13 +28,13 @@ const MyNodeTemplate: BlueprintNodeTemplate = {
 ## Implementing Node Executor
 
 ```typescript
-import { INodeExecutor, RegisterNode } from '@esengine/blueprint';
+import { INodeExecutor, RegisterNode, BlueprintNode, ExecutionContext, ExecutionResult } from '@esengine/blueprint';
 
 @RegisterNode(MyNodeTemplate)
 class MyNodeExecutor implements INodeExecutor {
     execute(node: BlueprintNode, context: ExecutionContext): ExecutionResult {
-        // Get input
-        const value = context.getInput<number>(node.id, 'value');
+        // Get input (using evaluateInput)
+        const value = context.evaluateInput(node.id, 'value', 0) as number;
 
         // Execute logic
         const result = value * 2;
@@ -100,29 +100,58 @@ const PureNodeTemplate: BlueprintNodeTemplate = {
 };
 ```
 
-## Example: Input Handler Node
+## Example: ECS Component Operation Node
 
 ```typescript
-const InputMoveTemplate: BlueprintNodeTemplate = {
-    type: 'InputMove',
-    title: 'Get Movement Input',
-    category: 'input',
-    inputs: [],
-    outputs: [
-        { name: 'direction', type: 'vector2', direction: 'output' }
+import type { Entity } from '@esengine/ecs-framework';
+import { BlueprintNodeTemplate, BlueprintNode } from '@esengine/blueprint';
+import { ExecutionContext, ExecutionResult } from '@esengine/blueprint';
+import { INodeExecutor, RegisterNode } from '@esengine/blueprint';
+
+// Custom heal node
+const HealEntityTemplate: BlueprintNodeTemplate = {
+    type: 'HealEntity',
+    title: 'Heal Entity',
+    category: 'gameplay',
+    color: '#22aa22',
+    description: 'Heal an entity with HealthComponent',
+    keywords: ['heal', 'health', 'restore'],
+    menuPath: ['Gameplay', 'Combat', 'Heal Entity'],
+    inputs: [
+        { name: 'exec', type: 'exec', displayName: '' },
+        { name: 'entity', type: 'entity', displayName: 'Target' },
+        { name: 'amount', type: 'float', displayName: 'Amount', defaultValue: 10 }
     ],
-    isPure: true
+    outputs: [
+        { name: 'exec', type: 'exec', displayName: '' },
+        { name: 'newHealth', type: 'float', displayName: 'New Health' }
+    ]
 };
 
-@RegisterNode(InputMoveTemplate)
-class InputMoveExecutor implements INodeExecutor {
+@RegisterNode(HealEntityTemplate)
+class HealEntityExecutor implements INodeExecutor {
     execute(node: BlueprintNode, context: ExecutionContext): ExecutionResult {
-        const input = context.scene.services.get(InputServiceToken);
-        const direction = {
-            x: input.getAxis('horizontal'),
-            y: input.getAxis('vertical')
-        };
-        return { outputs: { direction } };
+        const entity = context.evaluateInput(node.id, 'entity', context.entity) as Entity;
+        const amount = context.evaluateInput(node.id, 'amount', 10) as number;
+
+        if (!entity || entity.isDestroyed) {
+            return { outputs: { newHealth: 0 }, nextExec: 'exec' };
+        }
+
+        // Get HealthComponent
+        const health = entity.components.find(c =>
+            (c.constructor as any).__componentName__ === 'Health'
+        ) as any;
+
+        if (health) {
+            health.current = Math.min(health.current + amount, health.max);
+            return {
+                outputs: { newHealth: health.current },
+                nextExec: 'exec'
+            };
+        }
+
+        return { outputs: { newHealth: 0 }, nextExec: 'exec' };
     }
 }
 ```

docs/src/content/docs/en/modules/blueprint/examples.md

@@ -3,85 +3,127 @@ title: "Examples"
 description: "ECS integration and best practices"
 ---
 
-## Player Control Blueprint
+## Complete Game Integration Example
 
 ```typescript
-// Define input handling node
-const InputMoveTemplate: BlueprintNodeTemplate = {
-    type: 'InputMove',
-    title: 'Get Movement Input',
-    category: 'input',
-    inputs: [],
-    outputs: [
-        { name: 'direction', type: 'vector2', direction: 'output' }
-    ],
-    isPure: true
-};
+import { Scene, Core, Component, ECSComponent } from '@esengine/ecs-framework';
+import {
+    BlueprintSystem,
+    BlueprintComponent,
+    BlueprintExpose,
+    BlueprintProperty,
+    BlueprintMethod
+} from '@esengine/blueprint';
 
-@RegisterNode(InputMoveTemplate)
-class InputMoveExecutor implements INodeExecutor {
-    execute(node: BlueprintNode, context: ExecutionContext): ExecutionResult {
-        const input = context.scene.services.get(InputServiceToken);
-        const direction = {
-            x: input.getAxis('horizontal'),
-            y: input.getAxis('vertical')
-        };
-        return { outputs: { direction } };
+// 1. Define game components
+@ECSComponent('Player')
+@BlueprintExpose({ displayName: 'Player', category: 'gameplay' })
+export class PlayerComponent extends Component {
+    @BlueprintProperty({ displayName: 'Move Speed', type: 'float' })
+    moveSpeed: number = 5;
+
+    @BlueprintProperty({ displayName: 'Score', type: 'int' })
+    score: number = 0;
+
+    @BlueprintMethod({ displayName: 'Add Score' })
+    addScore(points: number): void {
+        this.score += points;
     }
 }
+
+@ECSComponent('Health')
+@BlueprintExpose({ displayName: 'Health', category: 'gameplay' })
+export class HealthComponent extends Component {
+    @BlueprintProperty({ displayName: 'Current Health' })
+    current: number = 100;
+
+    @BlueprintProperty({ displayName: 'Max Health' })
+    max: number = 100;
+
+    @BlueprintMethod({ displayName: 'Heal' })
+    heal(amount: number): void {
+        this.current = Math.min(this.current + amount, this.max);
+    }
+
+    @BlueprintMethod({ displayName: 'Take Damage' })
+    takeDamage(amount: number): boolean {
+        this.current -= amount;
+        return this.current <= 0;
+    }
+}
+
+// 2. Initialize game
+async function initGame() {
+    const scene = new Scene();
+
+    // Add blueprint system
+    scene.addSystem(new BlueprintSystem());
+
+    Core.setScene(scene);
+
+    // 3. Create player
+    const player = scene.createEntity('Player');
+    player.addComponent(new PlayerComponent());
+    player.addComponent(new HealthComponent());
+
+    // Add blueprint control
+    const blueprint = new BlueprintComponent();
+    blueprint.blueprintAsset = await loadBlueprintAsset('player.bp');
+    player.addComponent(blueprint);
+}
 ```
 
-## State Switching Logic
+## Custom Node Example
 
 ```typescript
-// Implement state machine logic in blueprint
-const stateBlueprint = createEmptyBlueprint('PlayerState');
+import type { Entity } from '@esengine/ecs-framework';
+import {
+    BlueprintNodeTemplate,
+    BlueprintNode,
+    ExecutionContext,
+    ExecutionResult,
+    INodeExecutor,
+    RegisterNode
+} from '@esengine/blueprint';
 
-// Add state variable
-stateBlueprint.variables.push({
-    name: 'currentState',
-    type: 'string',
-    defaultValue: 'idle',
-    scope: 'instance'
-});
-
-// Check state transitions in Tick event
-// ... implemented via node connections
-```
-
-## Damage Handling System
-
-```typescript
 // Custom damage node
 const ApplyDamageTemplate: BlueprintNodeTemplate = {
     type: 'ApplyDamage',
     title: 'Apply Damage',
     category: 'combat',
+    color: '#aa2222',
+    description: 'Apply damage to entity with Health component',
+    keywords: ['damage', 'hurt', 'attack'],
+    menuPath: ['Combat', 'Apply Damage'],
     inputs: [
-        { name: 'exec', type: 'exec', direction: 'input', isExec: true },
-        { name: 'target', type: 'entity', direction: 'input' },
-        { name: 'amount', type: 'number', direction: 'input', defaultValue: 10 }
+        { name: 'exec', type: 'exec', displayName: '' },
+        { name: 'target', type: 'entity', displayName: 'Target' },
+        { name: 'amount', type: 'float', displayName: 'Damage', defaultValue: 10 }
     ],
     outputs: [
-        { name: 'exec', type: 'exec', direction: 'output', isExec: true },
-        { name: 'killed', type: 'boolean', direction: 'output' }
+        { name: 'exec', type: 'exec', displayName: '' },
+        { name: 'killed', type: 'bool', displayName: 'Killed' }
     ]
 };
 
 @RegisterNode(ApplyDamageTemplate)
 class ApplyDamageExecutor implements INodeExecutor {
     execute(node: BlueprintNode, context: ExecutionContext): ExecutionResult {
-        const target = context.getInput<Entity>(node.id, 'target');
-        const amount = context.getInput<number>(node.id, 'amount');
+        const target = context.evaluateInput(node.id, 'target', context.entity) as Entity;
+        const amount = context.evaluateInput(node.id, 'amount', 10) as number;
+
+        if (!target || target.isDestroyed) {
+            return { outputs: { killed: false }, nextExec: 'exec' };
+        }
+
+        const health = target.components.find(c =>
+            (c.constructor as any).__componentName__ === 'Health'
+        ) as any;
 
-        const health = target.getComponent(HealthComponent);
         if (health) {
             health.current -= amount;
             const killed = health.current <= 0;
-            return {
-                outputs: { killed },
-                nextExec: 'exec'
-            };
+            return { outputs: { killed }, nextExec: 'exec' };
         }
 
         return { outputs: { killed: false }, nextExec: 'exec' };
@@ -132,7 +174,8 @@ vm.maxStepsPerFrame = 1000;
 
 ```typescript
 // Enable debug mode for execution logs
-vm.debug = true;
+const blueprint = entity.getComponent(BlueprintComponent);
+blueprint.debug = true;
 
 // Use Print nodes for intermediate values
 // Set breakpoints in editor

docs/src/content/docs/en/modules/blueprint/index.md

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

docs/src/content/docs/en/modules/blueprint/nodes.md

@@ -1,107 +1,118 @@
 ---
-title: "Built-in Nodes"
-description: "Blueprint built-in node reference"
+title: "ECS Node Reference"
+description: "Blueprint built-in ECS operation nodes"
 ---
 
 ## Event Nodes
 
+Lifecycle events as blueprint entry points:
+
 | Node | Description |
 |------|-------------|
 | `EventBeginPlay` | Triggered when blueprint starts |
-| `EventTick` | Triggered each frame |
+| `EventTick` | Triggered each frame, receives deltaTime |
 | `EventEndPlay` | Triggered when blueprint stops |
-| `EventCollision` | Triggered on collision |
-| `EventInput` | Triggered on input event |
-| `EventTimer` | Triggered by timer |
-| `EventMessage` | Triggered by custom message |
+
+## Entity Nodes
+
+ECS entity operations:
+
+| Node | Description | Type |
+|------|-------------|------|
+| `Get Self` | Get entity owning this blueprint | Pure |
+| `Create Entity` | Create new entity in scene | Execution |
+| `Destroy Entity` | Destroy specified entity | Execution |
+| `Destroy Self` | Destroy self entity | Execution |
+| `Is Valid` | Check if entity is valid | Pure |
+| `Get Entity Name` | Get entity name | Pure |
+| `Set Entity Name` | Set entity name | Execution |
+| `Get Entity Tag` | Get entity tag | Pure |
+| `Set Entity Tag` | Set entity tag | Execution |
+| `Set Active` | Set entity active state | Execution |
+| `Is Active` | Check if entity is active | Pure |
+| `Find Entity By Name` | Find entity by name | Pure |
+| `Find Entities By Tag` | Find all entities by tag | Pure |
+| `Get Entity ID` | Get entity unique ID | Pure |
+| `Find Entity By ID` | Find entity by ID | Pure |
+
+## Component Nodes
+
+ECS component operations:
+
+| Node | Description | Type |
+|------|-------------|------|
+| `Has Component` | Check if entity has specified component | Pure |
+| `Get Component` | Get component from entity | Pure |
+| `Get All Components` | Get all components from entity | Pure |
+| `Remove Component` | Remove component | Execution |
+| `Get Component Property` | Get component property value | Pure |
+| `Set Component Property` | Set component property value | Execution |
+| `Get Component Type` | Get component type name | Pure |
+| `Get Owner Entity` | Get owning entity from component | Pure |
 
 ## Flow Control Nodes
 
+Control execution flow:
+
 | Node | Description |
 |------|-------------|
 | `Branch` | Conditional branch (if/else) |
 | `Sequence` | Execute multiple outputs in sequence |
-| `ForLoop` | Loop execution |
-| `WhileLoop` | Conditional loop |
-| `DoOnce` | Execute only once |
-| `FlipFlop` | Alternate between two branches |
+| `For Loop` | Loop execution |
+| `For Each` | Iterate array |
+| `While Loop` | Conditional loop |
+| `Do Once` | Execute only once |
+| `Flip Flop` | Alternate between two branches |
 | `Gate` | Toggleable execution gate |
 
 ## Time Nodes
 
-| Node | Description |
-|------|-------------|
-| `Delay` | Delay execution |
-| `GetDeltaTime` | Get frame delta time |
-| `GetTime` | Get runtime |
-| `SetTimer` | Set timer |
-| `ClearTimer` | Clear timer |
+| Node | Description | Type |
+|------|-------------|------|
+| `Delay` | Delay execution | Execution |
+| `Get Delta Time` | Get frame delta time | Pure |
+| `Get Time` | Get total runtime | Pure |
 
 ## Math Nodes
 
 | Node | Description |
 |------|-------------|
-| `Add` | Addition |
-| `Subtract` | Subtraction |
-| `Multiply` | Multiplication |
-| `Divide` | Division |
+| `Add` / `Subtract` / `Multiply` / `Divide` | Basic operations |
 | `Abs` | Absolute value |
 | `Clamp` | Clamp to range |
 | `Lerp` | Linear interpolation |
 | `Min` / `Max` | Minimum/Maximum |
-| `Sin` / `Cos` | Trigonometric functions |
-| `Sqrt` | Square root |
-| `Power` | Power |
-
-## Logic Nodes
-
-| Node | Description |
-|------|-------------|
-| `And` | Logical AND |
-| `Or` | Logical OR |
-| `Not` | Logical NOT |
-| `Equal` | Equality comparison |
-| `NotEqual` | Inequality comparison |
-| `Greater` | Greater than comparison |
-| `Less` | Less than comparison |
-
-## Vector Nodes
-
-| Node | Description |
-|------|-------------|
-| `MakeVector2` | Create 2D vector |
-| `BreakVector2` | Break 2D vector |
-| `VectorAdd` | Vector addition |
-| `VectorSubtract` | Vector subtraction |
-| `VectorMultiply` | Vector multiplication |
-| `VectorLength` | Vector length |
-| `VectorNormalize` | Vector normalization |
-| `VectorDistance` | Vector distance |
-
-## Entity Nodes
-
-| Node | Description |
-|------|-------------|
-| `GetSelf` | Get current entity |
-| `GetComponent` | Get component |
-| `HasComponent` | Check component |
-| `AddComponent` | Add component |
-| `RemoveComponent` | Remove component |
-| `SpawnEntity` | Create entity |
-| `DestroyEntity` | Destroy entity |
-
-## Variable Nodes
-
-| Node | Description |
-|------|-------------|
-| `GetVariable` | Get variable value |
-| `SetVariable` | Set variable value |
 
 ## Debug Nodes
 
 | Node | Description |
 |------|-------------|
 | `Print` | Print to console |
-| `DrawDebugLine` | Draw debug line |
-| `DrawDebugPoint` | Draw debug point |
-| `Breakpoint` | Debug breakpoint |
+
+## Auto-generated Component Nodes
+
+Components marked with `@BlueprintExpose` decorator auto-generate nodes:
+
+```typescript
+@ECSComponent('Transform')
+@BlueprintExpose({ displayName: 'Transform', category: 'core' })
+export class TransformComponent extends Component {
+    @BlueprintProperty({ displayName: 'X Position' })
+    x: number = 0;
+
+    @BlueprintProperty({ displayName: 'Y Position' })
+    y: number = 0;
+
+    @BlueprintMethod({ displayName: 'Translate' })
+    translate(dx: number, dy: number): void {
+        this.x += dx;
+        this.y += dy;
+    }
+}
+```
+
+Generated nodes:
+- **Get Transform** - Get Transform component
+- **Get X Position** / **Set X Position** - Access x property
+- **Get Y Position** / **Set Y Position** - Access y property
+- **Translate** - Call translate method

docs/src/content/docs/en/modules/blueprint/vm.md

@@ -45,7 +45,7 @@ interface ExecutionContext {
     time: number;               // Total runtime
 
     // Get input value
-    getInput<T>(nodeId: string, pinName: string): T;
+    evaluateInput(nodeId: string, pinName: string, defaultValue: unknown): unknown;
 
     // Set output value
     setOutput(nodeId: string, pinName: string, value: unknown): void;
@@ -70,35 +70,33 @@ interface ExecutionResult {
 
 ## ECS Integration
 
-### Using Blueprint System
+### Using Built-in Blueprint System
 
 ```typescript
-import { createBlueprintSystem } from '@esengine/blueprint';
+import { Scene, Core } from '@esengine/ecs-framework';
+import { BlueprintSystem, BlueprintComponent } from '@esengine/blueprint';
 
-class GameScene {
-    private blueprintSystem: BlueprintSystem;
+// Add blueprint system to scene
+const scene = new Scene();
+scene.addSystem(new BlueprintSystem());
+Core.setScene(scene);
 
-    initialize() {
-        this.blueprintSystem = createBlueprintSystem(this.scene);
-    }
-
-    update(dt: number) {
-        // Process all entities with blueprint components
-        this.blueprintSystem.process(this.entities, dt);
-    }
-}
+// Add blueprint to entity
+const entity = scene.createEntity('Player');
+const blueprint = new BlueprintComponent();
+blueprint.blueprintAsset = await loadBlueprintAsset('player.bp');
+entity.addComponent(blueprint);
 ```
 
 ### Triggering Blueprint Events
 
 ```typescript
-import { triggerBlueprintEvent, triggerCustomBlueprintEvent } from '@esengine/blueprint';
-
-// Trigger built-in event
-triggerBlueprintEvent(entity, 'Collision', { other: otherEntity });
-
-// Trigger custom event
-triggerCustomBlueprintEvent(entity, 'OnPickup', { item: itemEntity });
+// Get blueprint component from entity and trigger events
+const blueprint = entity.getComponent(BlueprintComponent);
+if (blueprint?.vm) {
+    blueprint.vm.triggerEvent('EventCollision', { other: otherEntity });
+    blueprint.vm.triggerCustomEvent('OnPickup', { item: itemEntity });
+}
 ```
 
 ## Serialization

docs/src/content/docs/en/modules/database-drivers/index.md

@@ -0,0 +1,136 @@
+---
+title: "Database Drivers"
+description: "MongoDB, Redis connection management and driver abstraction"
+---
+
+`@esengine/database-drivers` is ESEngine's database connection management layer, providing unified connection management for MongoDB, Redis, and more.
+
+## Features
+
+- **Connection Pool** - Automatic connection pool management
+- **Auto Reconnect** - Automatic reconnection on disconnect
+- **Event Notification** - Connection state change events
+- **Type Decoupling** - Simplified interfaces, no dependency on native driver types
+- **Shared Connections** - Single connection shared across modules
+
+## Installation
+
+```bash
+npm install @esengine/database-drivers
+```
+
+**Peer Dependencies:**
+```bash
+npm install mongodb    # For MongoDB support
+npm install ioredis    # For Redis support
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  @esengine/database-drivers (Layer 1)                           │
+│  ┌─────────────────────┐  ┌─────────────────────┐               │
+│  │   MongoConnection   │  │   RedisConnection   │               │
+│  │   - Pool management │  │   - Auto-reconnect  │               │
+│  │   - Auto-reconnect  │  │   - Key prefix      │               │
+│  │   - Event emitter   │  │   - Event emitter   │               │
+│  └──────────┬──────────┘  └─────────────────────┘               │
+│             │                                                    │
+│  ┌──────────▼──────────┐                                        │
+│  │ IMongoCollection<T> │  ← Type-safe interface                 │
+│  │ (Adapter pattern)   │    decoupled from mongodb types        │
+│  └─────────────────────┘                                        │
+└─────────────────────────────────────────────────────────────────┘
+            │
+            ▼
+┌───────────────────────┐  ┌───────────────────────┐
+│  @esengine/database   │  │ @esengine/transaction │
+│  (Repository pattern) │  │ (Distributed tx)      │
+└───────────────────────┘  └───────────────────────┘
+```
+
+## Quick Start
+
+### MongoDB Connection
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+
+// Create connection
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game',
+    pool: {
+        minSize: 5,
+        maxSize: 20
+    },
+    autoReconnect: true
+})
+
+// Listen to events
+mongo.on('connected', () => console.log('MongoDB connected'))
+mongo.on('disconnected', () => console.log('MongoDB disconnected'))
+mongo.on('error', (e) => console.error('Error:', e.error))
+
+// Connect
+await mongo.connect()
+
+// Use collections
+const users = mongo.collection<User>('users')
+await users.insertOne({ name: 'John', score: 100 })
+
+const user = await users.findOne({ name: 'John' })
+
+// Disconnect when done
+await mongo.disconnect()
+```
+
+### Redis Connection
+
+```typescript
+import { createRedisConnection } from '@esengine/database-drivers'
+
+const redis = createRedisConnection({
+    host: 'localhost',
+    port: 6379,
+    keyPrefix: 'game:',
+    autoReconnect: true
+})
+
+await redis.connect()
+
+// Basic operations
+await redis.set('session:123', 'data', 3600)  // With TTL
+const value = await redis.get('session:123')
+
+await redis.disconnect()
+```
+
+## Service Container Integration
+
+```typescript
+import { ServiceContainer } from '@esengine/ecs-framework'
+import {
+    createMongoConnection,
+    MongoConnectionToken,
+    RedisConnectionToken
+} from '@esengine/database-drivers'
+
+const services = new ServiceContainer()
+
+// Register connections
+const mongo = createMongoConnection({ uri: '...', database: 'game' })
+await mongo.connect()
+services.register(MongoConnectionToken, mongo)
+
+// Retrieve in other modules
+const connection = services.get(MongoConnectionToken)
+const users = connection.collection('users')
+```
+
+## Documentation
+
+- [MongoDB Connection](/en/modules/database-drivers/mongo/) - MongoDB configuration details
+- [Redis Connection](/en/modules/database-drivers/redis/) - Redis configuration details
+- [Service Tokens](/en/modules/database-drivers/tokens/) - Dependency injection integration

docs/src/content/docs/en/modules/database-drivers/mongo.md

@@ -0,0 +1,265 @@
+---
+title: "MongoDB Connection"
+description: "MongoDB connection management, connection pooling, auto-reconnect"
+---
+
+## Configuration Options
+
+```typescript
+interface MongoConnectionConfig {
+    /** MongoDB connection URI */
+    uri: string
+
+    /** Database name */
+    database: string
+
+    /** Connection pool configuration */
+    pool?: {
+        minSize?: number      // Minimum connections
+        maxSize?: number      // Maximum connections
+        acquireTimeout?: number  // Connection acquire timeout (ms)
+        maxLifetime?: number     // Maximum connection lifetime (ms)
+    }
+
+    /** Auto-reconnect (default true) */
+    autoReconnect?: boolean
+
+    /** Reconnect interval (ms, default 5000) */
+    reconnectInterval?: number
+
+    /** Maximum reconnect attempts (default 10) */
+    maxReconnectAttempts?: number
+}
+```
+
+## Complete Example
+
+```typescript
+import { createMongoConnection, MongoConnectionToken } from '@esengine/database-drivers'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game',
+    pool: {
+        minSize: 5,
+        maxSize: 20,
+        acquireTimeout: 5000,
+        maxLifetime: 300000
+    },
+    autoReconnect: true,
+    reconnectInterval: 5000,
+    maxReconnectAttempts: 10
+})
+
+// Event listeners
+mongo.on('connected', () => {
+    console.log('MongoDB connected')
+})
+
+mongo.on('disconnected', () => {
+    console.log('MongoDB disconnected')
+})
+
+mongo.on('reconnecting', () => {
+    console.log('MongoDB reconnecting...')
+})
+
+mongo.on('reconnected', () => {
+    console.log('MongoDB reconnected')
+})
+
+mongo.on('error', (event) => {
+    console.error('MongoDB error:', event.error)
+})
+
+// Connect
+await mongo.connect()
+
+// Check status
+console.log('Connected:', mongo.isConnected())
+console.log('Ping:', await mongo.ping())
+```
+
+## IMongoConnection Interface
+
+```typescript
+interface IMongoConnection {
+    /** Connection ID */
+    readonly id: string
+
+    /** Connection state */
+    readonly state: ConnectionState
+
+    /** Establish connection */
+    connect(): Promise<void>
+
+    /** Disconnect */
+    disconnect(): Promise<void>
+
+    /** Check if connected */
+    isConnected(): boolean
+
+    /** Test connection */
+    ping(): Promise<boolean>
+
+    /** Get typed collection */
+    collection<T extends object>(name: string): IMongoCollection<T>
+
+    /** Get database interface */
+    getDatabase(): IMongoDatabase
+
+    /** Get native client (advanced usage) */
+    getNativeClient(): MongoClientType
+
+    /** Get native database (advanced usage) */
+    getNativeDatabase(): Db
+}
+```
+
+## IMongoCollection Interface
+
+Type-safe collection interface, decoupled from native MongoDB types:
+
+```typescript
+interface IMongoCollection<T extends object> {
+    readonly name: string
+
+    // Query
+    findOne(filter: object, options?: FindOptions): Promise<T | null>
+    find(filter: object, options?: FindOptions): Promise<T[]>
+    countDocuments(filter?: object): Promise<number>
+
+    // Insert
+    insertOne(doc: T): Promise<InsertOneResult>
+    insertMany(docs: T[]): Promise<InsertManyResult>
+
+    // Update
+    updateOne(filter: object, update: object): Promise<UpdateResult>
+    updateMany(filter: object, update: object): Promise<UpdateResult>
+    findOneAndUpdate(
+        filter: object,
+        update: object,
+        options?: FindOneAndUpdateOptions
+    ): Promise<T | null>
+
+    // Delete
+    deleteOne(filter: object): Promise<DeleteResult>
+    deleteMany(filter: object): Promise<DeleteResult>
+
+    // Index
+    createIndex(
+        spec: Record<string, 1 | -1>,
+        options?: IndexOptions
+    ): Promise<string>
+}
+```
+
+## Usage Examples
+
+### Basic CRUD
+
+```typescript
+interface User {
+    id: string
+    name: string
+    email: string
+    score: number
+}
+
+const users = mongo.collection<User>('users')
+
+// Insert
+await users.insertOne({
+    id: '1',
+    name: 'John',
+    email: 'john@example.com',
+    score: 100
+})
+
+// Query
+const user = await users.findOne({ name: 'John' })
+
+const topUsers = await users.find(
+    { score: { $gte: 100 } },
+    { sort: { score: -1 }, limit: 10 }
+)
+
+// Update
+await users.updateOne(
+    { id: '1' },
+    { $inc: { score: 10 } }
+)
+
+// Delete
+await users.deleteOne({ id: '1' })
+```
+
+### Batch Operations
+
+```typescript
+// Batch insert
+await users.insertMany([
+    { id: '1', name: 'Alice', email: 'alice@example.com', score: 100 },
+    { id: '2', name: 'Bob', email: 'bob@example.com', score: 200 },
+    { id: '3', name: 'Carol', email: 'carol@example.com', score: 150 }
+])
+
+// Batch update
+await users.updateMany(
+    { score: { $lt: 100 } },
+    { $set: { status: 'inactive' } }
+)
+
+// Batch delete
+await users.deleteMany({ status: 'inactive' })
+```
+
+### Index Management
+
+```typescript
+// Create indexes
+await users.createIndex({ email: 1 }, { unique: true })
+await users.createIndex({ score: -1 })
+await users.createIndex({ name: 1, score: -1 })
+```
+
+## Integration with Other Modules
+
+### With @esengine/database
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { UserRepository, createRepository } from '@esengine/database'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+// Use UserRepository
+const userRepo = new UserRepository(mongo)
+await userRepo.register({ username: 'john', password: '123456' })
+
+// Use generic repository
+const playerRepo = createRepository<Player>(mongo, 'players')
+```
+
+### With @esengine/transaction
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { createMongoStorage, TransactionManager } from '@esengine/transaction'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+// Create transaction storage (shared connection)
+const storage = createMongoStorage(mongo)
+await storage.ensureIndexes()
+
+const txManager = new TransactionManager({ storage })
+```

docs/src/content/docs/en/modules/database-drivers/redis.md

@@ -0,0 +1,228 @@
+---
+title: "Redis Connection"
+description: "Redis connection management, auto-reconnect, key prefix"
+---
+
+## Configuration Options
+
+```typescript
+interface RedisConnectionConfig {
+    /** Redis host */
+    host?: string
+
+    /** Redis port */
+    port?: number
+
+    /** Authentication password */
+    password?: string
+
+    /** Database number */
+    db?: number
+
+    /** Key prefix */
+    keyPrefix?: string
+
+    /** Auto-reconnect (default true) */
+    autoReconnect?: boolean
+
+    /** Reconnect interval (ms, default 5000) */
+    reconnectInterval?: number
+
+    /** Maximum reconnect attempts (default 10) */
+    maxReconnectAttempts?: number
+}
+```
+
+## Complete Example
+
+```typescript
+import { createRedisConnection, RedisConnectionToken } from '@esengine/database-drivers'
+
+const redis = createRedisConnection({
+    host: 'localhost',
+    port: 6379,
+    password: 'your-password',
+    db: 0,
+    keyPrefix: 'game:',
+    autoReconnect: true,
+    reconnectInterval: 5000,
+    maxReconnectAttempts: 10
+})
+
+// Event listeners
+redis.on('connected', () => {
+    console.log('Redis connected')
+})
+
+redis.on('disconnected', () => {
+    console.log('Redis disconnected')
+})
+
+redis.on('error', (event) => {
+    console.error('Redis error:', event.error)
+})
+
+// Connect
+await redis.connect()
+
+// Check status
+console.log('Connected:', redis.isConnected())
+console.log('Ping:', await redis.ping())
+```
+
+## IRedisConnection Interface
+
+```typescript
+interface IRedisConnection {
+    /** Connection ID */
+    readonly id: string
+
+    /** Connection state */
+    readonly state: ConnectionState
+
+    /** Establish connection */
+    connect(): Promise<void>
+
+    /** Disconnect */
+    disconnect(): Promise<void>
+
+    /** Check if connected */
+    isConnected(): boolean
+
+    /** Test connection */
+    ping(): Promise<boolean>
+
+    /** Get value */
+    get(key: string): Promise<string | null>
+
+    /** Set value (optional TTL in seconds) */
+    set(key: string, value: string, ttl?: number): Promise<void>
+
+    /** Delete key */
+    del(key: string): Promise<boolean>
+
+    /** Check if key exists */
+    exists(key: string): Promise<boolean>
+
+    /** Set expiration (seconds) */
+    expire(key: string, seconds: number): Promise<boolean>
+
+    /** Get remaining TTL (seconds) */
+    ttl(key: string): Promise<number>
+
+    /** Get native client (advanced usage) */
+    getNativeClient(): Redis
+}
+```
+
+## Usage Examples
+
+### Basic Operations
+
+```typescript
+// Set value
+await redis.set('user:1:name', 'John')
+
+// Set value with expiration (1 hour)
+await redis.set('session:abc123', 'user-data', 3600)
+
+// Get value
+const name = await redis.get('user:1:name')
+
+// Check if key exists
+const exists = await redis.exists('user:1:name')
+
+// Delete key
+await redis.del('user:1:name')
+
+// Get remaining TTL
+const ttl = await redis.ttl('session:abc123')
+```
+
+### Key Prefix
+
+When `keyPrefix` is configured, all operations automatically add the prefix:
+
+```typescript
+const redis = createRedisConnection({
+    host: 'localhost',
+    keyPrefix: 'game:'
+})
+
+// Actual key is 'game:user:1'
+await redis.set('user:1', 'data')
+
+// Actual key queried is 'game:user:1'
+const data = await redis.get('user:1')
+```
+
+### Advanced Operations
+
+Use native client for advanced operations:
+
+```typescript
+const client = redis.getNativeClient()
+
+// Using Pipeline
+const pipeline = client.pipeline()
+pipeline.set('key1', 'value1')
+pipeline.set('key2', 'value2')
+pipeline.set('key3', 'value3')
+await pipeline.exec()
+
+// Using Transactions
+const multi = client.multi()
+multi.incr('counter')
+multi.get('counter')
+const results = await multi.exec()
+
+// Using Lua Scripts
+const result = await client.eval(
+    `return redis.call('get', KEYS[1])`,
+    1,
+    'mykey'
+)
+```
+
+## Integration with Transaction System
+
+```typescript
+import { createRedisConnection } from '@esengine/database-drivers'
+import { RedisStorage, TransactionManager } from '@esengine/transaction'
+
+const redis = createRedisConnection({
+    host: 'localhost',
+    port: 6379,
+    keyPrefix: 'tx:'
+})
+await redis.connect()
+
+// Create transaction storage
+const storage = new RedisStorage({
+    factory: () => redis.getNativeClient(),
+    prefix: 'tx:'
+})
+
+const txManager = new TransactionManager({ storage })
+```
+
+## Connection State
+
+```typescript
+type ConnectionState =
+    | 'disconnected'  // Not connected
+    | 'connecting'    // Connecting
+    | 'connected'     // Connected
+    | 'disconnecting' // Disconnecting
+    | 'error'         // Error state
+```
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `connected` | Connection established |
+| `disconnected` | Connection closed |
+| `reconnecting` | Reconnecting |
+| `reconnected` | Reconnection successful |
+| `error` | Error occurred |

docs/src/content/docs/en/modules/database/index.md

@@ -0,0 +1,217 @@
+---
+title: "Database Repository"
+description: "Repository pattern database layer with CRUD, pagination, and soft delete"
+---
+
+`@esengine/database` is ESEngine's database operation layer, providing type-safe CRUD operations based on the Repository pattern.
+
+## Features
+
+- **Repository Pattern** - Generic CRUD operations with type safety
+- **Pagination** - Built-in pagination support
+- **Soft Delete** - Optional soft delete with restore
+- **User Management** - Ready-to-use UserRepository
+- **Password Security** - Secure password hashing with scrypt
+
+## Installation
+
+```bash
+npm install @esengine/database @esengine/database-drivers
+```
+
+## Quick Start
+
+### Basic Repository
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { Repository, createRepository } from '@esengine/database'
+
+// Define entity
+interface Player {
+    id: string
+    name: string
+    score: number
+    createdAt: Date
+    updatedAt: Date
+}
+
+// Create connection
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+// Create repository
+const playerRepo = createRepository<Player>(mongo, 'players')
+
+// CRUD operations
+const player = await playerRepo.create({
+    name: 'John',
+    score: 0
+})
+
+const found = await playerRepo.findById(player.id)
+
+await playerRepo.update(player.id, { score: 100 })
+
+await playerRepo.delete(player.id)
+```
+
+### Custom Repository
+
+```typescript
+import { Repository, BaseEntity } from '@esengine/database'
+import type { IMongoConnection } from '@esengine/database-drivers'
+
+interface Player extends BaseEntity {
+    name: string
+    score: number
+    rank?: string
+}
+
+class PlayerRepository extends Repository<Player> {
+    constructor(connection: IMongoConnection) {
+        super(connection, 'players')
+    }
+
+    async findTopPlayers(limit: number = 10): Promise<Player[]> {
+        return this.findMany({
+            sort: { score: 'desc' },
+            limit
+        })
+    }
+
+    async findByRank(rank: string): Promise<Player[]> {
+        return this.findMany({
+            where: { rank }
+        })
+    }
+}
+
+// Usage
+const playerRepo = new PlayerRepository(mongo)
+const topPlayers = await playerRepo.findTopPlayers(5)
+```
+
+### User Repository
+
+```typescript
+import { UserRepository } from '@esengine/database'
+
+const userRepo = new UserRepository(mongo)
+
+// Register new user
+const user = await userRepo.register({
+    username: 'john',
+    password: 'securePassword123',
+    email: 'john@example.com'
+})
+
+// Authenticate
+const authenticated = await userRepo.authenticate('john', 'securePassword123')
+if (authenticated) {
+    console.log('Login successful:', authenticated.username)
+}
+
+// Change password
+await userRepo.changePassword(user.id, 'securePassword123', 'newPassword456')
+
+// Role management
+await userRepo.addRole(user.id, 'admin')
+await userRepo.removeRole(user.id, 'admin')
+
+// Find users
+const admins = await userRepo.findByRole('admin')
+const john = await userRepo.findByUsername('john')
+```
+
+### Pagination
+
+```typescript
+const result = await playerRepo.findPaginated(
+    { page: 1, pageSize: 20 },
+    {
+        where: { rank: 'gold' },
+        sort: { score: 'desc' }
+    }
+)
+
+console.log(result.data)        // Player[]
+console.log(result.total)       // Total count
+console.log(result.totalPages)  // Total pages
+console.log(result.hasNext)     // Has next page
+console.log(result.hasPrev)     // Has previous page
+```
+
+### Soft Delete
+
+```typescript
+// Enable soft delete
+const playerRepo = createRepository<Player>(mongo, 'players', true)
+
+// Delete (marks as deleted)
+await playerRepo.delete(playerId)
+
+// Find excludes soft-deleted by default
+const players = await playerRepo.findMany()
+
+// Include soft-deleted records
+const allPlayers = await playerRepo.findMany({
+    includeSoftDeleted: true
+})
+
+// Restore soft-deleted record
+await playerRepo.restore(playerId)
+```
+
+### Query Options
+
+```typescript
+// Complex queries
+const players = await playerRepo.findMany({
+    where: {
+        score: { $gte: 100 },
+        rank: { $in: ['gold', 'platinum'] },
+        name: { $like: 'John%' }
+    },
+    sort: {
+        score: 'desc',
+        name: 'asc'
+    },
+    limit: 10,
+    offset: 0
+})
+
+// OR conditions
+const players = await playerRepo.findMany({
+    where: {
+        $or: [
+            { score: { $gte: 1000 } },
+            { rank: 'legendary' }
+        ]
+    }
+})
+```
+
+## Query Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$eq` | Equal | `{ score: { $eq: 100 } }` |
+| `$ne` | Not equal | `{ status: { $ne: 'banned' } }` |
+| `$gt` | Greater than | `{ score: { $gt: 50 } }` |
+| `$gte` | Greater or equal | `{ level: { $gte: 10 } }` |
+| `$lt` | Less than | `{ age: { $lt: 18 } }` |
+| `$lte` | Less or equal | `{ price: { $lte: 100 } }` |
+| `$in` | In array | `{ rank: { $in: ['gold', 'platinum'] } }` |
+| `$nin` | Not in array | `{ status: { $nin: ['banned'] } }` |
+| `$like` | Pattern match | `{ name: { $like: '%john%' } }` |
+| `$regex` | Regex match | `{ email: { $regex: '@gmail.com$' } }` |
+
+## Documentation
+
+- [Repository API](/en/modules/database/repository/) - Repository detailed API
+- [User Management](/en/modules/database/user/) - UserRepository usage
+- [Query Syntax](/en/modules/database/query/) - Query condition syntax

docs/src/content/docs/en/modules/database/query.md

@@ -0,0 +1,185 @@
+---
+title: "Query Syntax"
+description: "Query condition operators and syntax"
+---
+
+## Basic Queries
+
+### Exact Match
+
+```typescript
+await repo.findMany({
+    where: {
+        name: 'John',
+        status: 'active'
+    }
+})
+```
+
+### Using Operators
+
+```typescript
+await repo.findMany({
+    where: {
+        score: { $gte: 100 },
+        rank: { $in: ['gold', 'platinum'] }
+    }
+})
+```
+
+## Query Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$eq` | Equal | `{ score: { $eq: 100 } }` |
+| `$ne` | Not equal | `{ status: { $ne: 'banned' } }` |
+| `$gt` | Greater than | `{ score: { $gt: 50 } }` |
+| `$gte` | Greater than or equal | `{ level: { $gte: 10 } }` |
+| `$lt` | Less than | `{ age: { $lt: 18 } }` |
+| `$lte` | Less than or equal | `{ price: { $lte: 100 } }` |
+| `$in` | In array | `{ rank: { $in: ['gold', 'platinum'] } }` |
+| `$nin` | Not in array | `{ status: { $nin: ['banned', 'suspended'] } }` |
+| `$like` | Pattern match | `{ name: { $like: '%john%' } }` |
+| `$regex` | Regex match | `{ email: { $regex: '@gmail.com$' } }` |
+
+## Logical Operators
+
+### $or
+
+```typescript
+await repo.findMany({
+    where: {
+        $or: [
+            { score: { $gte: 1000 } },
+            { rank: 'legendary' }
+        ]
+    }
+})
+```
+
+### $and
+
+```typescript
+await repo.findMany({
+    where: {
+        $and: [
+            { score: { $gte: 100 } },
+            { score: { $lte: 500 } }
+        ]
+    }
+})
+```
+
+### Combined Usage
+
+```typescript
+await repo.findMany({
+    where: {
+        status: 'active',
+        $or: [
+            { rank: 'gold' },
+            { score: { $gte: 1000 } }
+        ]
+    }
+})
+```
+
+## Pattern Matching
+
+### $like Syntax
+
+- `%` - Matches any sequence of characters
+- `_` - Matches single character
+
+```typescript
+// Starts with 'John'
+{ name: { $like: 'John%' } }
+
+// Ends with 'son'
+{ name: { $like: '%son' } }
+
+// Contains 'oh'
+{ name: { $like: '%oh%' } }
+
+// Second character is 'o'
+{ name: { $like: '_o%' } }
+```
+
+### $regex Syntax
+
+Uses standard regular expressions:
+
+```typescript
+// Starts with 'John' (case insensitive)
+{ name: { $regex: '^john' } }
+
+// Gmail email
+{ email: { $regex: '@gmail\\.com$' } }
+
+// Contains numbers
+{ username: { $regex: '\\d+' } }
+```
+
+## Sorting
+
+```typescript
+await repo.findMany({
+    sort: {
+        score: 'desc',  // Descending
+        name: 'asc'     // Ascending
+    }
+})
+```
+
+## Pagination
+
+### Using limit/offset
+
+```typescript
+// First page
+await repo.findMany({
+    limit: 20,
+    offset: 0
+})
+
+// Second page
+await repo.findMany({
+    limit: 20,
+    offset: 20
+})
+```
+
+### Using findPaginated
+
+```typescript
+const result = await repo.findPaginated(
+    { page: 2, pageSize: 20 },
+    { sort: { createdAt: 'desc' } }
+)
+```
+
+## Complete Examples
+
+```typescript
+// Find active gold players with scores between 100-1000
+// Sort by score descending, get top 10
+const players = await repo.findMany({
+    where: {
+        status: 'active',
+        rank: 'gold',
+        score: { $gte: 100, $lte: 1000 }
+    },
+    sort: { score: 'desc' },
+    limit: 10
+})
+
+// Search for users with 'john' in username or gmail email
+const users = await repo.findMany({
+    where: {
+        $or: [
+            { username: { $like: '%john%' } },
+            { email: { $regex: '@gmail\\.com$' } }
+        ]
+    }
+})
+```

docs/src/content/docs/en/modules/database/repository.md

@@ -0,0 +1,244 @@
+---
+title: "Repository API"
+description: "Generic repository interface, CRUD operations, pagination, soft delete"
+---
+
+## Creating a Repository
+
+### Using Factory Function
+
+```typescript
+import { createRepository } from '@esengine/database'
+
+const playerRepo = createRepository<Player>(mongo, 'players')
+
+// Enable soft delete
+const playerRepo = createRepository<Player>(mongo, 'players', true)
+```
+
+### Extending Repository
+
+```typescript
+import { Repository, BaseEntity } from '@esengine/database'
+
+interface Player extends BaseEntity {
+    name: string
+    score: number
+}
+
+class PlayerRepository extends Repository<Player> {
+    constructor(connection: IMongoConnection) {
+        super(connection, 'players', false)  // Third param: enable soft delete
+    }
+
+    // Add custom methods
+    async findTopPlayers(limit: number): Promise<Player[]> {
+        return this.findMany({
+            sort: { score: 'desc' },
+            limit
+        })
+    }
+}
+```
+
+## BaseEntity Interface
+
+All entities must extend `BaseEntity`:
+
+```typescript
+interface BaseEntity {
+    id: string
+    createdAt: Date
+    updatedAt: Date
+    deletedAt?: Date  // Used for soft delete
+}
+```
+
+## Query Methods
+
+### findById
+
+```typescript
+const player = await repo.findById('player-123')
+```
+
+### findOne
+
+```typescript
+const player = await repo.findOne({
+    where: { name: 'John' }
+})
+
+const topPlayer = await repo.findOne({
+    sort: { score: 'desc' }
+})
+```
+
+### findMany
+
+```typescript
+// Simple query
+const players = await repo.findMany({
+    where: { rank: 'gold' }
+})
+
+// Complex query
+const players = await repo.findMany({
+    where: {
+        score: { $gte: 100 },
+        rank: { $in: ['gold', 'platinum'] }
+    },
+    sort: { score: 'desc', name: 'asc' },
+    limit: 10,
+    offset: 0
+})
+```
+
+### findPaginated
+
+```typescript
+const result = await repo.findPaginated(
+    { page: 1, pageSize: 20 },
+    {
+        where: { rank: 'gold' },
+        sort: { score: 'desc' }
+    }
+)
+
+console.log(result.data)        // Player[]
+console.log(result.total)       // Total count
+console.log(result.totalPages)  // Total pages
+console.log(result.hasNext)     // Has next page
+console.log(result.hasPrev)     // Has previous page
+```
+
+### count
+
+```typescript
+const count = await repo.count({
+    where: { rank: 'gold' }
+})
+```
+
+### exists
+
+```typescript
+const exists = await repo.exists({
+    where: { email: 'john@example.com' }
+})
+```
+
+## Create Methods
+
+### create
+
+```typescript
+const player = await repo.create({
+    name: 'John',
+    score: 0
+})
+// Automatically generates id, createdAt, updatedAt
+```
+
+### createMany
+
+```typescript
+const players = await repo.createMany([
+    { name: 'Alice', score: 100 },
+    { name: 'Bob', score: 200 },
+    { name: 'Carol', score: 150 }
+])
+```
+
+## Update Methods
+
+### update
+
+```typescript
+const updated = await repo.update('player-123', {
+    score: 200,
+    rank: 'gold'
+})
+// Automatically updates updatedAt
+```
+
+## Delete Methods
+
+### delete
+
+```typescript
+// Hard delete
+await repo.delete('player-123')
+
+// Soft delete (if enabled)
+// Actually sets the deletedAt field
+```
+
+### deleteMany
+
+```typescript
+const count = await repo.deleteMany({
+    where: { score: { $lt: 10 } }
+})
+```
+
+## Soft Delete
+
+### Enabling Soft Delete
+
+```typescript
+const repo = createRepository<Player>(mongo, 'players', true)
+```
+
+### Query Behavior
+
+```typescript
+// Excludes soft-deleted records by default
+const players = await repo.findMany()
+
+// Include soft-deleted records
+const allPlayers = await repo.findMany({
+    includeSoftDeleted: true
+})
+```
+
+### Restore Records
+
+```typescript
+await repo.restore('player-123')
+```
+
+## QueryOptions
+
+```typescript
+interface QueryOptions<T> {
+    /** Query conditions */
+    where?: WhereCondition<T>
+
+    /** Sorting */
+    sort?: Partial<Record<keyof T, 'asc' | 'desc'>>
+
+    /** Limit count */
+    limit?: number
+
+    /** Offset */
+    offset?: number
+
+    /** Include soft-deleted records (only when soft delete is enabled) */
+    includeSoftDeleted?: boolean
+}
+```
+
+## PaginatedResult
+
+```typescript
+interface PaginatedResult<T> {
+    data: T[]
+    total: number
+    page: number
+    pageSize: number
+    totalPages: number
+    hasNext: boolean
+    hasPrev: boolean
+}
+```

docs/src/content/docs/en/modules/database/user.md

@@ -0,0 +1,277 @@
+---
+title: "User Management"
+description: "UserRepository for user registration, authentication, and role management"
+---
+
+## Overview
+
+`UserRepository` provides out-of-the-box user management features:
+
+- User registration and authentication
+- Password hashing (using scrypt)
+- Role management
+- Account status management
+
+## Quick Start
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { UserRepository } from '@esengine/database'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+const userRepo = new UserRepository(mongo)
+```
+
+## User Registration
+
+```typescript
+const user = await userRepo.register({
+    username: 'john',
+    password: 'securePassword123',
+    email: 'john@example.com',      // Optional
+    displayName: 'John Doe',         // Optional
+    roles: ['player']                // Optional, defaults to []
+})
+
+console.log(user)
+// {
+//   id: 'uuid-...',
+//   username: 'john',
+//   email: 'john@example.com',
+//   displayName: 'John Doe',
+//   roles: ['player'],
+//   status: 'active',
+//   createdAt: Date,
+//   updatedAt: Date
+// }
+```
+
+**Note**: `register` returns a `SafeUser` which excludes the password hash.
+
+## User Authentication
+
+```typescript
+const user = await userRepo.authenticate('john', 'securePassword123')
+
+if (user) {
+    console.log('Login successful:', user.username)
+} else {
+    console.log('Invalid username or password')
+}
+```
+
+## Password Management
+
+### Change Password
+
+```typescript
+const success = await userRepo.changePassword(
+    userId,
+    'oldPassword123',
+    'newPassword456'
+)
+
+if (success) {
+    console.log('Password changed successfully')
+} else {
+    console.log('Invalid current password')
+}
+```
+
+### Reset Password
+
+```typescript
+// Admin directly resets password
+const success = await userRepo.resetPassword(userId, 'newPassword123')
+```
+
+## Role Management
+
+### Add Role
+
+```typescript
+await userRepo.addRole(userId, 'admin')
+await userRepo.addRole(userId, 'moderator')
+```
+
+### Remove Role
+
+```typescript
+await userRepo.removeRole(userId, 'moderator')
+```
+
+### Query Roles
+
+```typescript
+// Find all admins
+const admins = await userRepo.findByRole('admin')
+
+// Check if user has a role
+const user = await userRepo.findById(userId)
+const isAdmin = user?.roles.includes('admin')
+```
+
+## Querying Users
+
+### Find by Username
+
+```typescript
+const user = await userRepo.findByUsername('john')
+```
+
+### Find by Email
+
+```typescript
+const user = await userRepo.findByEmail('john@example.com')
+```
+
+### Find by Role
+
+```typescript
+const admins = await userRepo.findByRole('admin')
+```
+
+### Using Inherited Methods
+
+```typescript
+// Paginated query
+const result = await userRepo.findPaginated(
+    { page: 1, pageSize: 20 },
+    {
+        where: { status: 'active' },
+        sort: { createdAt: 'desc' }
+    }
+)
+
+// Complex query
+const users = await userRepo.findMany({
+    where: {
+        status: 'active',
+        roles: { $in: ['admin', 'moderator'] }
+    }
+})
+```
+
+## Account Status
+
+```typescript
+type UserStatus = 'active' | 'inactive' | 'banned' | 'suspended'
+```
+
+### Update Status
+
+```typescript
+await userRepo.update(userId, { status: 'banned' })
+```
+
+### Query by Status
+
+```typescript
+const activeUsers = await userRepo.findMany({
+    where: { status: 'active' }
+})
+
+const bannedUsers = await userRepo.findMany({
+    where: { status: 'banned' }
+})
+```
+
+## Type Definitions
+
+### UserEntity
+
+```typescript
+interface UserEntity extends BaseEntity {
+    username: string
+    passwordHash: string
+    email?: string
+    displayName?: string
+    roles: string[]
+    status: UserStatus
+    lastLoginAt?: Date
+}
+```
+
+### SafeUser
+
+```typescript
+type SafeUser = Omit<UserEntity, 'passwordHash'>
+```
+
+### CreateUserParams
+
+```typescript
+interface CreateUserParams {
+    username: string
+    password: string
+    email?: string
+    displayName?: string
+    roles?: string[]
+}
+```
+
+## Password Utilities
+
+Standalone password utility functions:
+
+```typescript
+import { hashPassword, verifyPassword } from '@esengine/database'
+
+// Hash password
+const hash = await hashPassword('myPassword123')
+
+// Verify password
+const isValid = await verifyPassword('myPassword123', hash)
+```
+
+### Security Notes
+
+- Uses Node.js built-in `scrypt` algorithm
+- Automatically generates random salt
+- Uses secure iteration parameters by default
+- Hash format: `salt:hash` (both hex encoded)
+
+## Extending UserRepository
+
+```typescript
+import { UserRepository, UserEntity } from '@esengine/database'
+
+interface GameUser extends UserEntity {
+    level: number
+    experience: number
+    coins: number
+}
+
+class GameUserRepository extends UserRepository {
+    // Override collection name
+    constructor(connection: IMongoConnection) {
+        super(connection, 'game_users')
+    }
+
+    // Add game-related methods
+    async addExperience(userId: string, amount: number): Promise<GameUser | null> {
+        const user = await this.findById(userId) as GameUser | null
+        if (!user) return null
+
+        const newExp = user.experience + amount
+        const newLevel = Math.floor(newExp / 1000) + 1
+
+        return this.update(userId, {
+            experience: newExp,
+            level: newLevel
+        }) as Promise<GameUser | null>
+    }
+
+    async findTopPlayers(limit: number = 10): Promise<GameUser[]> {
+        return this.findMany({
+            sort: { level: 'desc', experience: 'desc' },
+            limit
+        }) as Promise<GameUser[]>
+    }
+}
+```

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

@@ -36,6 +36,13 @@ ESEngine provides a rich set of modules that can be imported as needed.
 | [Network](/en/modules/network/) | `@esengine/network` | Multiplayer game networking |
 | [Transaction](/en/modules/transaction/) | `@esengine/transaction` | Game transactions with distributed support |
 
+### Database
+
+| Module | Package | Description |
+|--------|---------|-------------|
+| [Database Drivers](/en/modules/database-drivers/) | `@esengine/database-drivers` | MongoDB, Redis connection management |
+| [Database Repository](/en/modules/database/) | `@esengine/database` | Repository pattern data operations |
+
 ## Installation
 
 All modules can be installed independently:

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

@@ -92,6 +92,355 @@ const token = jwtProvider.sign({
 const payload = jwtProvider.decode(token)
 ```
 
+### Custom Provider
+
+You can create custom authentication providers by implementing the `IAuthProvider` interface to integrate with any authentication system (OAuth, LDAP, custom database auth, etc.).
+
+#### IAuthProvider Interface
+
+```typescript
+interface IAuthProvider<TUser = unknown, TCredentials = unknown> {
+    /** Provider name */
+    readonly name: string;
+
+    /** Verify credentials */
+    verify(credentials: TCredentials): Promise<AuthResult<TUser>>;
+
+    /** Refresh token (optional) */
+    refresh?(token: string): Promise<AuthResult<TUser>>;
+
+    /** Revoke token (optional) */
+    revoke?(token: string): Promise<boolean>;
+}
+
+interface AuthResult<TUser> {
+    success: boolean;
+    user?: TUser;
+    error?: string;
+    errorCode?: AuthErrorCode;
+    token?: string;
+    expiresAt?: number;
+}
+
+type AuthErrorCode =
+    | 'INVALID_CREDENTIALS'
+    | 'EXPIRED_TOKEN'
+    | 'INVALID_TOKEN'
+    | 'USER_NOT_FOUND'
+    | 'ACCOUNT_DISABLED'
+    | 'RATE_LIMITED'
+    | 'INSUFFICIENT_PERMISSIONS';
+```
+
+#### Custom Provider Examples
+
+**Example 1: Database Password Authentication**
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface User {
+    id: string
+    username: string
+    roles: string[]
+}
+
+interface PasswordCredentials {
+    username: string
+    password: string
+}
+
+class DatabaseAuthProvider implements IAuthProvider<User, PasswordCredentials> {
+    readonly name = 'database'
+
+    async verify(credentials: PasswordCredentials): Promise<AuthResult<User>> {
+        const { username, password } = credentials
+
+        // Query user from database
+        const user = await db.users.findByUsername(username)
+        if (!user) {
+            return {
+                success: false,
+                error: 'User not found',
+                errorCode: 'USER_NOT_FOUND'
+            }
+        }
+
+        // Verify password (using bcrypt or similar)
+        const isValid = await bcrypt.compare(password, user.passwordHash)
+        if (!isValid) {
+            return {
+                success: false,
+                error: 'Invalid password',
+                errorCode: 'INVALID_CREDENTIALS'
+            }
+        }
+
+        // Check account status
+        if (user.disabled) {
+            return {
+                success: false,
+                error: 'Account is disabled',
+                errorCode: 'ACCOUNT_DISABLED'
+            }
+        }
+
+        return {
+            success: true,
+            user: {
+                id: user.id,
+                username: user.username,
+                roles: user.roles
+            }
+        }
+    }
+}
+```
+
+**Example 2: OAuth/Third-party Authentication**
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface OAuthUser {
+    id: string
+    email: string
+    name: string
+    provider: string
+    roles: string[]
+}
+
+interface OAuthCredentials {
+    provider: 'google' | 'github' | 'discord'
+    accessToken: string
+}
+
+class OAuthProvider implements IAuthProvider<OAuthUser, OAuthCredentials> {
+    readonly name = 'oauth'
+
+    async verify(credentials: OAuthCredentials): Promise<AuthResult<OAuthUser>> {
+        const { provider, accessToken } = credentials
+
+        try {
+            // Verify token with provider
+            const profile = await this.fetchUserProfile(provider, accessToken)
+
+            // Find or create local user
+            let user = await db.users.findByOAuth(provider, profile.id)
+            if (!user) {
+                user = await db.users.create({
+                    oauthProvider: provider,
+                    oauthId: profile.id,
+                    email: profile.email,
+                    name: profile.name,
+                    roles: ['player']
+                })
+            }
+
+            return {
+                success: true,
+                user: {
+                    id: user.id,
+                    email: user.email,
+                    name: user.name,
+                    provider,
+                    roles: user.roles
+                }
+            }
+        } catch (error) {
+            return {
+                success: false,
+                error: 'OAuth verification failed',
+                errorCode: 'INVALID_TOKEN'
+            }
+        }
+    }
+
+    private async fetchUserProfile(provider: string, token: string) {
+        switch (provider) {
+            case 'google':
+                return fetch('https://www.googleapis.com/oauth2/v2/userinfo', {
+                    headers: { Authorization: `Bearer ${token}` }
+                }).then(r => r.json())
+            case 'github':
+                return fetch('https://api.github.com/user', {
+                    headers: { Authorization: `Bearer ${token}` }
+                }).then(r => r.json())
+            // Other providers...
+            default:
+                throw new Error(`Unsupported provider: ${provider}`)
+        }
+    }
+}
+```
+
+**Example 3: API Key Authentication**
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface ApiUser {
+    id: string
+    name: string
+    roles: string[]
+    rateLimit: number
+}
+
+class ApiKeyAuthProvider implements IAuthProvider<ApiUser, string> {
+    readonly name = 'api-key'
+
+    private revokedKeys = new Set<string>()
+
+    async verify(apiKey: string): Promise<AuthResult<ApiUser>> {
+        if (!apiKey || !apiKey.startsWith('sk_')) {
+            return {
+                success: false,
+                error: 'Invalid API Key format',
+                errorCode: 'INVALID_TOKEN'
+            }
+        }
+
+        if (this.revokedKeys.has(apiKey)) {
+            return {
+                success: false,
+                error: 'API Key has been revoked',
+                errorCode: 'INVALID_TOKEN'
+            }
+        }
+
+        // Query API Key from database
+        const keyData = await db.apiKeys.findByKey(apiKey)
+        if (!keyData) {
+            return {
+                success: false,
+                error: 'API Key not found',
+                errorCode: 'INVALID_CREDENTIALS'
+            }
+        }
+
+        // Check expiration
+        if (keyData.expiresAt && keyData.expiresAt < Date.now()) {
+            return {
+                success: false,
+                error: 'API Key has expired',
+                errorCode: 'EXPIRED_TOKEN'
+            }
+        }
+
+        return {
+            success: true,
+            user: {
+                id: keyData.userId,
+                name: keyData.name,
+                roles: keyData.roles,
+                rateLimit: keyData.rateLimit
+            },
+            expiresAt: keyData.expiresAt
+        }
+    }
+
+    async revoke(apiKey: string): Promise<boolean> {
+        this.revokedKeys.add(apiKey)
+        await db.apiKeys.revoke(apiKey)
+        return true
+    }
+}
+```
+
+#### Using Custom Providers
+
+```typescript
+import { createServer } from '@esengine/server'
+import { withAuth } from '@esengine/server/auth'
+
+// Create custom provider
+const dbAuthProvider = new DatabaseAuthProvider()
+
+// Or use OAuth provider
+const oauthProvider = new OAuthProvider()
+
+// Use custom provider
+const server = withAuth(await createServer({ port: 3000 }), {
+    provider: dbAuthProvider, // or oauthProvider
+
+    // Extract credentials from WebSocket connection request
+    extractCredentials: (req) => {
+        const url = new URL(req.url, 'http://localhost')
+
+        // For database auth: get from query params
+        const username = url.searchParams.get('username')
+        const password = url.searchParams.get('password')
+        if (username && password) {
+            return { username, password }
+        }
+
+        // For OAuth: get from token param
+        const provider = url.searchParams.get('provider')
+        const accessToken = url.searchParams.get('access_token')
+        if (provider && accessToken) {
+            return { provider, accessToken }
+        }
+
+        // For API Key: get from header
+        const apiKey = req.headers['x-api-key']
+        if (apiKey) {
+            return apiKey as string
+        }
+
+        return null
+    },
+
+    onAuthFailure: (conn, error) => {
+        console.log(`Auth failed: ${error.errorCode} - ${error.error}`)
+    }
+})
+
+await server.start()
+```
+
+#### Combining Multiple Providers
+
+You can create a composite provider to support multiple authentication methods:
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface MultiAuthCredentials {
+    type: 'jwt' | 'oauth' | 'apikey' | 'password'
+    data: unknown
+}
+
+class MultiAuthProvider implements IAuthProvider<User, MultiAuthCredentials> {
+    readonly name = 'multi'
+
+    constructor(
+        private jwtProvider: JwtAuthProvider<User>,
+        private oauthProvider: OAuthProvider,
+        private apiKeyProvider: ApiKeyAuthProvider,
+        private dbProvider: DatabaseAuthProvider
+    ) {}
+
+    async verify(credentials: MultiAuthCredentials): Promise<AuthResult<User>> {
+        switch (credentials.type) {
+            case 'jwt':
+                return this.jwtProvider.verify(credentials.data as string)
+            case 'oauth':
+                return this.oauthProvider.verify(credentials.data as OAuthCredentials)
+            case 'apikey':
+                return this.apiKeyProvider.verify(credentials.data as string)
+            case 'password':
+                return this.dbProvider.verify(credentials.data as PasswordCredentials)
+            default:
+                return {
+                    success: false,
+                    error: 'Unsupported authentication type',
+                    errorCode: 'INVALID_CREDENTIALS'
+                }
+        }
+    }
+}
+```
+
 ### Session Provider
 
 Use server-side sessions for stateful authentication:

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

@@ -0,0 +1,441 @@
+---
+title: "Distributed Rooms"
+description: "Multi-server room management with DistributedRoomManager"
+---
+
+## Overview
+
+Distributed room support allows multiple server instances to share a room registry, enabling cross-server player routing and failover.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Server A          Server B          Server C          │
+│  ┌─────────┐       ┌─────────┐       ┌─────────┐       │
+│  │ Room 1  │       │ Room 3  │       │ Room 5  │       │
+│  │ Room 2  │       │ Room 4  │       │ Room 6  │       │
+│  └────┬────┘       └────┬────┘       └────┬────┘       │
+│       │                 │                 │             │
+│       └─────────────────┼─────────────────┘             │
+│                         │                               │
+│              ┌──────────▼──────────┐                    │
+│              │  IDistributedAdapter │                   │
+│              │  (Redis / Memory)    │                   │
+│              └─────────────────────┘                    │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Quick Start
+
+### Single Server Mode (Testing)
+
+```typescript
+import {
+    DistributedRoomManager,
+    MemoryAdapter,
+    Room
+} from '@esengine/server';
+
+// Define room type
+class GameRoom extends Room {
+    maxPlayers = 4;
+}
+
+// Create adapter and manager
+const adapter = new MemoryAdapter();
+const manager = new DistributedRoomManager(adapter, {
+    serverId: 'server-1',
+    serverAddress: 'localhost',
+    serverPort: 3000
+}, (conn, type, data) => conn.send(JSON.stringify({ type, data })));
+
+// Register room type
+manager.define('game', GameRoom);
+
+// Start manager
+await manager.start();
+
+// Distributed join/create room
+const result = await manager.joinOrCreateDistributed('game', 'player-1', conn);
+if ('redirect' in result) {
+    // Player should connect to another server
+    console.log(`Redirect to: ${result.redirect}`);
+} else {
+    // Player joined local room
+    const { room, player } = result;
+}
+
+// Graceful shutdown
+await manager.stop(true);
+```
+
+### Multi-Server Mode (Production)
+
+```typescript
+import Redis from 'ioredis';
+import { DistributedRoomManager, RedisAdapter } from '@esengine/server';
+
+const adapter = new RedisAdapter({
+    factory: () => new Redis({
+        host: 'redis.example.com',
+        port: 6379
+    }),
+    prefix: 'game:',
+    serverTtl: 30,
+    snapshotTtl: 86400
+});
+
+const manager = new DistributedRoomManager(adapter, {
+    serverId: process.env.SERVER_ID,
+    serverAddress: process.env.PUBLIC_IP,
+    serverPort: 3000,
+    heartbeatInterval: 5000,
+    snapshotInterval: 30000,
+    enableFailover: true,
+    capacity: 100
+}, sendFn);
+```
+
+## DistributedRoomManager
+
+### Configuration Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `serverId` | `string` | required | Unique server identifier |
+| `serverAddress` | `string` | required | Public address for client connections |
+| `serverPort` | `number` | required | Server port |
+| `heartbeatInterval` | `number` | `5000` | Heartbeat interval (ms) |
+| `snapshotInterval` | `number` | `30000` | State snapshot interval, 0 to disable |
+| `migrationTimeout` | `number` | `10000` | Room migration timeout |
+| `enableFailover` | `boolean` | `true` | Enable automatic failover |
+| `capacity` | `number` | `100` | Max rooms on this server |
+
+### Lifecycle Methods
+
+#### start()
+
+Start the distributed room manager. Connects to adapter, registers server, starts heartbeat.
+
+```typescript
+await manager.start();
+```
+
+#### stop(graceful?)
+
+Stop the manager. If `graceful=true`, marks server as draining and saves all room snapshots.
+
+```typescript
+await manager.stop(true);
+```
+
+### Routing Methods
+
+#### joinOrCreateDistributed()
+
+Join or create a room with distributed awareness. Returns `{ room, player }` for local rooms or `{ redirect: string }` for remote rooms.
+
+```typescript
+const result = await manager.joinOrCreateDistributed('game', 'player-1', conn);
+
+if ('redirect' in result) {
+    // Client should redirect to another server
+    res.json({ redirect: result.redirect });
+} else {
+    // Player joined local room
+    const { room, player } = result;
+}
+```
+
+#### route()
+
+Route a player to the appropriate room/server.
+
+```typescript
+const result = await manager.route({
+    roomType: 'game',
+    playerId: 'p1'
+});
+
+switch (result.type) {
+    case 'local':      // Room is on this server
+        break;
+    case 'redirect':   // Room is on another server
+        // result.serverAddress contains target server
+        break;
+    case 'create':     // No room exists, need to create
+        break;
+    case 'unavailable': // Cannot find or create room
+        // result.reason contains error message
+        break;
+}
+```
+
+### State Management
+
+#### saveSnapshot()
+
+Manually save a room's state snapshot.
+
+```typescript
+await manager.saveSnapshot(roomId);
+```
+
+#### restoreFromSnapshot()
+
+Restore a room from its saved snapshot.
+
+```typescript
+const success = await manager.restoreFromSnapshot(roomId);
+```
+
+### Query Methods
+
+#### getServers()
+
+Get all online servers.
+
+```typescript
+const servers = await manager.getServers();
+```
+
+#### queryDistributedRooms()
+
+Query rooms across all servers.
+
+```typescript
+const rooms = await manager.queryDistributedRooms({
+    roomType: 'game',
+    hasSpace: true,
+    notLocked: true
+});
+```
+
+## IDistributedAdapter
+
+Interface for distributed backends. Implement this to add support for Redis, message queues, etc.
+
+### Built-in Adapters
+
+#### MemoryAdapter
+
+In-memory implementation for testing and single-server mode.
+
+```typescript
+const adapter = new MemoryAdapter({
+    serverTtl: 15000,      // Server offline after no heartbeat (ms)
+    enableTtlCheck: true,  // Enable automatic TTL checking
+    ttlCheckInterval: 5000 // TTL check interval (ms)
+});
+```
+
+#### RedisAdapter
+
+Redis-based implementation for production multi-server deployments.
+
+```typescript
+import Redis from 'ioredis';
+import { RedisAdapter } from '@esengine/server';
+
+const adapter = new RedisAdapter({
+    factory: () => new Redis('redis://localhost:6379'),
+    prefix: 'game:',       // Key prefix (default: 'dist:')
+    serverTtl: 30,         // Server TTL in seconds (default: 30)
+    roomTtl: 0,            // Room TTL, 0 = never expire (default: 0)
+    snapshotTtl: 86400,    // Snapshot TTL in seconds (default: 24h)
+    channel: 'game:events' // Pub/Sub channel (default: 'distributed:events')
+});
+```
+
+**RedisAdapter Configuration:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `factory` | `() => RedisClient` | required | Redis client factory (lazy connection) |
+| `prefix` | `string` | `'dist:'` | Key prefix for all Redis keys |
+| `serverTtl` | `number` | `30` | Server TTL in seconds |
+| `roomTtl` | `number` | `0` | Room TTL in seconds, 0 = no expiry |
+| `snapshotTtl` | `number` | `86400` | Snapshot TTL in seconds |
+| `channel` | `string` | `'distributed:events'` | Pub/Sub channel name |
+
+**Features:**
+- Server registry with automatic heartbeat TTL
+- Room registry with cross-server lookup
+- State snapshots with configurable TTL
+- Pub/Sub for cross-server events
+- Distributed locks using Redis SET NX
+
+### Custom Adapters
+
+```typescript
+import type { IDistributedAdapter } from '@esengine/server';
+
+class MyAdapter implements IDistributedAdapter {
+    // Lifecycle
+    async connect(): Promise<void> { }
+    async disconnect(): Promise<void> { }
+    isConnected(): boolean { return true; }
+
+    // Server Registry
+    async registerServer(server: ServerRegistration): Promise<void> { }
+    async unregisterServer(serverId: string): Promise<void> { }
+    async heartbeat(serverId: string): Promise<void> { }
+    async getServers(): Promise<ServerRegistration[]> { return []; }
+
+    // Room Registry
+    async registerRoom(room: RoomRegistration): Promise<void> { }
+    async unregisterRoom(roomId: string): Promise<void> { }
+    async queryRooms(query: RoomQuery): Promise<RoomRegistration[]> { return []; }
+    async findAvailableRoom(roomType: string): Promise<RoomRegistration | null> { return null; }
+
+    // State Snapshots
+    async saveSnapshot(snapshot: RoomSnapshot): Promise<void> { }
+    async loadSnapshot(roomId: string): Promise<RoomSnapshot | null> { return null; }
+
+    // Pub/Sub
+    async publish(event: DistributedEvent): Promise<void> { }
+    async subscribe(pattern: string, handler: Function): Promise<() => void> { return () => {}; }
+
+    // Distributed Locks
+    async acquireLock(key: string, ttlMs: number): Promise<boolean> { return true; }
+    async releaseLock(key: string): Promise<void> { }
+}
+```
+
+## Player Routing Flow
+
+```
+Client                    Server A                    Server B
+  │                          │                           │
+  │─── joinOrCreate ────────►│                           │
+  │                          │                           │
+  │                          │── findAvailableRoom() ───►│
+  │                          │◄──── room on Server B ────│
+  │                          │                           │
+  │◄─── redirect: B:3001 ────│                           │
+  │                          │                           │
+  │───────────────── connect to Server B ───────────────►│
+  │                          │                           │
+  │◄─────────────────────────────── joined ─────────────│
+```
+
+## Event Types
+
+The distributed system publishes these events:
+
+| Event | Description |
+|-------|-------------|
+| `server:online` | Server came online |
+| `server:offline` | Server went offline |
+| `server:draining` | Server is draining |
+| `room:created` | Room was created |
+| `room:disposed` | Room was disposed |
+| `room:updated` | Room info updated |
+| `room:message` | Cross-server room message |
+| `room:migrated` | Room migrated to another server |
+| `player:joined` | Player joined room |
+| `player:left` | Player left room |
+
+## Best Practices
+
+1. **Use Unique Server IDs** - Use hostname, container ID, or UUID
+
+2. **Configure Proper Heartbeat** - Balance between freshness and network overhead
+
+3. **Enable Snapshots for Stateful Rooms** - Ensure room state survives server restarts
+
+4. **Handle Redirects Gracefully** - Client should reconnect to target server
+   ```typescript
+   // Client handling redirect
+   if (response.redirect) {
+       await client.disconnect();
+       await client.connect(response.redirect);
+       await client.joinRoom(roomId);
+   }
+   ```
+
+5. **Use Distributed Locks** - Prevent race conditions in joinOrCreate
+
+## Using createServer Integration
+
+The simplest way to use distributed rooms is through `createServer`'s `distributed` config:
+
+```typescript
+import { createServer } from '@esengine/server';
+import { RedisAdapter, Room } from '@esengine/server';
+import Redis from 'ioredis';
+
+class GameRoom extends Room {
+    maxPlayers = 4;
+}
+
+const server = await createServer({
+    port: 3000,
+    distributed: {
+        enabled: true,
+        adapter: new RedisAdapter({ factory: () => new Redis() }),
+        serverId: 'server-1',
+        serverAddress: 'ws://192.168.1.100',
+        serverPort: 3000,
+        enableFailover: true,
+        capacity: 100
+    }
+});
+
+server.define('game', GameRoom);
+await server.start();
+```
+
+When clients call the `JoinRoom` API, the server will automatically:
+1. Find available rooms (local or remote)
+2. If room is on another server, send `$redirect` message to client
+3. Client receives redirect and connects to target server
+
+## Load Balancing
+
+Use `LoadBalancedRouter` for server selection:
+
+```typescript
+import { LoadBalancedRouter, createLoadBalancedRouter } from '@esengine/server';
+
+// Using factory function
+const router = createLoadBalancedRouter('least-players');
+
+// Or create directly
+const router = new LoadBalancedRouter({
+    strategy: 'least-rooms',  // Select server with fewest rooms
+    preferLocal: true         // Prefer local server
+});
+
+// Available strategies
+// - 'round-robin': Round robin selection
+// - 'least-rooms': Fewest rooms
+// - 'least-players': Fewest players
+// - 'random': Random selection
+// - 'weighted': Weighted by capacity usage
+```
+
+## Failover
+
+When a server goes offline with `enableFailover` enabled, the system will automatically:
+
+1. Detect server offline (via heartbeat timeout)
+2. Query all rooms on that server
+3. Use distributed lock to prevent multiple servers recovering same room
+4. Restore room state from snapshot
+5. Publish `room:migrated` event to notify other servers
+
+```typescript
+// Ensure periodic snapshots
+const manager = new DistributedRoomManager(adapter, {
+    serverId: 'server-1',
+    serverAddress: 'localhost',
+    serverPort: 3000,
+    snapshotInterval: 30000,  // Save snapshot every 30 seconds
+    enableFailover: true      // Enable failover
+}, sendFn);
+```
+
+## Future Releases
+
+- Redis Cluster support
+- More load balancing strategies (geo-location, latency-aware)

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

@@ -0,0 +1,679 @@
+---
+title: "HTTP Routing"
+description: "HTTP REST API routing with WebSocket port sharing support"
+---
+
+`@esengine/server` includes a lightweight HTTP routing feature that can share the same port with WebSocket services, making it easy to implement REST APIs.
+
+## Quick Start
+
+### Inline Route Definition
+
+The simplest way is to define HTTP routes directly when creating the server:
+
+```typescript
+import { createServer } from '@esengine/server'
+
+const server = await createServer({
+    port: 3000,
+    http: {
+        '/api/health': (req, res) => {
+            res.json({ status: 'ok', time: Date.now() })
+        },
+        '/api/users': {
+            GET: (req, res) => {
+                res.json({ users: [] })
+            },
+            POST: async (req, res) => {
+                const body = req.body as { name: string }
+                res.status(201).json({ id: '1', name: body.name })
+            }
+        }
+    },
+    cors: true  // Enable CORS
+})
+
+await server.start()
+```
+
+### File-based Routing
+
+For larger projects, file-based routing is recommended. Create a `src/http` directory where each file corresponds to a route:
+
+```typescript
+// src/http/login.ts
+import { defineHttp } from '@esengine/server'
+
+interface LoginBody {
+    username: string
+    password: string
+}
+
+export default defineHttp<LoginBody>({
+    method: 'POST',
+    handler(req, res) {
+        const { username, password } = req.body as LoginBody
+
+        // Validate user...
+        if (username === 'admin' && password === '123456') {
+            res.json({ token: 'jwt-token-here', userId: 'user-1' })
+        } else {
+            res.error(401, 'Invalid username or password')
+        }
+    }
+})
+```
+
+```typescript
+// server.ts
+import { createServer } from '@esengine/server'
+
+const server = await createServer({
+    port: 3000,
+    httpDir: './src/http',   // HTTP routes directory
+    httpPrefix: '/api',       // Route prefix
+    cors: true
+})
+
+await server.start()
+// Route: POST /api/login
+```
+
+## defineHttp Definition
+
+`defineHttp` is used to define type-safe HTTP handlers:
+
+```typescript
+import { defineHttp } from '@esengine/server'
+
+interface CreateUserBody {
+    username: string
+    email: string
+    password: string
+}
+
+export default defineHttp<CreateUserBody>({
+    // HTTP method (default POST)
+    method: 'POST',
+
+    // Handler function
+    handler(req, res) {
+        const body = req.body as CreateUserBody
+        // Handle request...
+        res.status(201).json({ id: 'new-user-id' })
+    }
+})
+```
+
+### Supported HTTP Methods
+
+```typescript
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS'
+```
+
+## HttpRequest Object
+
+The HTTP request object contains the following properties:
+
+```typescript
+interface HttpRequest {
+    /** Raw Node.js IncomingMessage */
+    raw: IncomingMessage
+
+    /** HTTP method */
+    method: string
+
+    /** Request path */
+    path: string
+
+    /** Route parameters (extracted from URL path, e.g., /users/:id) */
+    params: Record<string, string>
+
+    /** Query parameters */
+    query: Record<string, string>
+
+    /** Request headers */
+    headers: Record<string, string | string[] | undefined>
+
+    /** Parsed request body */
+    body: unknown
+
+    /** Client IP */
+    ip: string
+}
+```
+
+### Usage Examples
+
+```typescript
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // Get query parameters
+        const page = parseInt(req.query.page ?? '1')
+        const limit = parseInt(req.query.limit ?? '10')
+
+        // Get request headers
+        const authHeader = req.headers.authorization
+
+        // Get client IP
+        console.log('Request from:', req.ip)
+
+        res.json({ page, limit })
+    }
+})
+```
+
+### Body Parsing
+
+The request body is automatically parsed based on `Content-Type`:
+
+- `application/json` - Parsed as JSON object
+- `application/x-www-form-urlencoded` - Parsed as key-value object
+- Others - Kept as raw string
+
+```typescript
+export default defineHttp<{ name: string; age: number }>({
+    method: 'POST',
+    handler(req, res) {
+        // body is already parsed
+        const { name, age } = req.body as { name: string; age: number }
+        res.json({ received: { name, age } })
+    }
+})
+```
+
+## HttpResponse Object
+
+The HTTP response object provides a chainable API:
+
+```typescript
+interface HttpResponse {
+    /** Raw Node.js ServerResponse */
+    raw: ServerResponse
+
+    /** Set status code */
+    status(code: number): HttpResponse
+
+    /** Set response header */
+    header(name: string, value: string): HttpResponse
+
+    /** Send JSON response */
+    json(data: unknown): void
+
+    /** Send text response */
+    text(data: string): void
+
+    /** Send error response */
+    error(code: number, message: string): void
+}
+```
+
+### Usage Examples
+
+```typescript
+export default defineHttp({
+    method: 'POST',
+    handler(req, res) {
+        // Set status code and custom headers
+        res
+            .status(201)
+            .header('X-Custom-Header', 'value')
+            .json({ created: true })
+    }
+})
+```
+
+```typescript
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // Send error response
+        res.error(404, 'Resource not found')
+        // Equivalent to: res.status(404).json({ error: 'Resource not found' })
+    }
+})
+```
+
+```typescript
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // Send plain text
+        res.text('Hello, World!')
+    }
+})
+```
+
+## File Routing Conventions
+
+### Name Conversion
+
+File names are automatically converted to route paths:
+
+| File Path | Route Path (prefix=/api) |
+|-----------|-------------------------|
+| `login.ts` | `/api/login` |
+| `users/profile.ts` | `/api/users/profile` |
+| `users/[id].ts` | `/api/users/:id` |
+| `game/room/[roomId].ts` | `/api/game/room/:roomId` |
+
+### Dynamic Route Parameters
+
+Use `[param]` syntax to define dynamic parameters:
+
+```typescript
+// src/http/users/[id].ts
+import { defineHttp } from '@esengine/server'
+
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // Get route parameter directly from params
+        const { id } = req.params
+        res.json({ userId: id })
+    }
+})
+```
+
+Multiple parameters:
+
+```typescript
+// src/http/users/[userId]/posts/[postId].ts
+import { defineHttp } from '@esengine/server'
+
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        const { userId, postId } = req.params
+        res.json({ userId, postId })
+    }
+})
+```
+
+### Skip Rules
+
+The following files are automatically skipped:
+
+- Files starting with `_` (e.g., `_helper.ts`)
+- `index.ts` / `index.js` files
+- Non `.ts` / `.js` / `.mts` / `.mjs` files
+
+### Directory Structure Example
+
+```
+src/
+└── http/
+    ├── _utils.ts        # Skipped (underscore prefix)
+    ├── index.ts         # Skipped (index file)
+    ├── health.ts        # GET /api/health
+    ├── login.ts         # POST /api/login
+    ├── register.ts      # POST /api/register
+    └── users/
+        ├── index.ts     # Skipped
+        ├── list.ts      # GET /api/users/list
+        └── [id].ts      # GET /api/users/:id
+```
+
+## CORS Configuration
+
+### Quick Enable
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    cors: true  // Use default configuration
+})
+```
+
+### Custom Configuration
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    cors: {
+        // Allowed origins
+        origin: ['http://localhost:5173', 'https://myapp.com'],
+        // Or use wildcard
+        // origin: '*',
+        // origin: true,  // Reflect request origin
+
+        // Allowed HTTP methods
+        methods: ['GET', 'POST', 'PUT', 'DELETE'],
+
+        // Allowed request headers
+        allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
+
+        // Allow credentials (cookies)
+        credentials: true,
+
+        // Preflight cache max age (seconds)
+        maxAge: 86400
+    }
+})
+```
+
+### CorsOptions Type
+
+```typescript
+interface CorsOptions {
+    /** Allowed origins: string, string array, true (reflect) or '*' */
+    origin?: string | string[] | boolean
+
+    /** Allowed HTTP methods */
+    methods?: string[]
+
+    /** Allowed request headers */
+    allowedHeaders?: string[]
+
+    /** Allow credentials */
+    credentials?: boolean
+
+    /** Preflight cache max age (seconds) */
+    maxAge?: number
+}
+```
+
+## Route Merging
+
+File routes and inline routes can be used together, with inline routes having higher priority:
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    httpDir: './src/http',
+    httpPrefix: '/api',
+
+    // Inline routes merge with file routes
+    http: {
+        '/health': (req, res) => res.json({ status: 'ok' }),
+        '/api/special': (req, res) => res.json({ special: true })
+    }
+})
+```
+
+## Sharing Port with WebSocket
+
+HTTP routes automatically share the same port with WebSocket services:
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    // WebSocket related config
+    apiDir: './src/api',
+    msgDir: './src/msg',
+
+    // HTTP related config
+    httpDir: './src/http',
+    httpPrefix: '/api',
+    cors: true
+})
+
+await server.start()
+
+// Same port 3000:
+// - WebSocket: ws://localhost:3000
+// - HTTP API:  http://localhost:3000/api/*
+```
+
+## Complete Examples
+
+### Game Server Login API
+
+```typescript
+// src/http/auth/login.ts
+import { defineHttp } from '@esengine/server'
+import { createJwtAuthProvider } from '@esengine/server/auth'
+
+interface LoginRequest {
+    username: string
+    password: string
+}
+
+interface LoginResponse {
+    token: string
+    userId: string
+    expiresAt: number
+}
+
+const jwtProvider = createJwtAuthProvider({
+    secret: process.env.JWT_SECRET!,
+    expiresIn: 3600
+})
+
+export default defineHttp<LoginRequest>({
+    method: 'POST',
+    async handler(req, res) {
+        const { username, password } = req.body as LoginRequest
+
+        // Validate user
+        const user = await db.users.findByUsername(username)
+        if (!user || !await verifyPassword(password, user.passwordHash)) {
+            res.error(401, 'Invalid username or password')
+            return
+        }
+
+        // Generate JWT
+        const token = jwtProvider.sign({
+            sub: user.id,
+            name: user.username,
+            roles: user.roles
+        })
+
+        const response: LoginResponse = {
+            token,
+            userId: user.id,
+            expiresAt: Date.now() + 3600 * 1000
+        }
+
+        res.json(response)
+    }
+})
+```
+
+### Game Data Query API
+
+```typescript
+// src/http/game/leaderboard.ts
+import { defineHttp } from '@esengine/server'
+
+export default defineHttp({
+    method: 'GET',
+    async handler(req, res) {
+        const limit = parseInt(req.query.limit ?? '10')
+        const offset = parseInt(req.query.offset ?? '0')
+
+        const players = await db.players.findMany({
+            sort: { score: 'desc' },
+            limit,
+            offset
+        })
+
+        res.json({
+            data: players,
+            pagination: { limit, offset }
+        })
+    }
+})
+```
+
+## Middleware
+
+### Middleware Type
+
+Middleware are functions that execute before and after route handlers:
+
+```typescript
+type HttpMiddleware = (
+    req: HttpRequest,
+    res: HttpResponse,
+    next: () => Promise<void>
+) => void | Promise<void>
+```
+
+### Built-in Middleware
+
+```typescript
+import {
+    requestLogger,
+    bodyLimit,
+    responseTime,
+    requestId,
+    securityHeaders
+} from '@esengine/server'
+
+const server = await createServer({
+    port: 3000,
+    http: { /* ... */ },
+    // Global middleware configured via createHttpRouter
+})
+```
+
+#### requestLogger - Request Logging
+
+```typescript
+import { requestLogger } from '@esengine/server'
+
+// Log request and response time
+requestLogger()
+
+// Also log request body
+requestLogger({ logBody: true })
+```
+
+#### bodyLimit - Request Body Size Limit
+
+```typescript
+import { bodyLimit } from '@esengine/server'
+
+// Limit request body to 1MB
+bodyLimit(1024 * 1024)
+```
+
+#### responseTime - Response Time Header
+
+```typescript
+import { responseTime } from '@esengine/server'
+
+// Automatically add X-Response-Time header
+responseTime()
+```
+
+#### requestId - Request ID
+
+```typescript
+import { requestId } from '@esengine/server'
+
+// Auto-generate and add X-Request-ID header
+requestId()
+
+// Custom header name
+requestId('X-Trace-ID')
+```
+
+#### securityHeaders - Security Headers
+
+```typescript
+import { securityHeaders } from '@esengine/server'
+
+// Add common security response headers
+securityHeaders()
+
+// Custom configuration
+securityHeaders({
+    hidePoweredBy: true,
+    frameOptions: 'DENY',
+    noSniff: true
+})
+```
+
+### Custom Middleware
+
+```typescript
+import type { HttpMiddleware } from '@esengine/server'
+
+// Authentication middleware
+const authMiddleware: HttpMiddleware = async (req, res, next) => {
+    const token = req.headers.authorization?.replace('Bearer ', '')
+
+    if (!token) {
+        res.error(401, 'Unauthorized')
+        return  // Don't call next(), terminate request
+    }
+
+    // Validate token...
+    (req as any).userId = 'decoded-user-id'
+
+    await next()  // Continue to next middleware and handler
+}
+```
+
+### Using Middleware
+
+#### With createHttpRouter
+
+```typescript
+import { createHttpRouter, requestLogger, bodyLimit } from '@esengine/server'
+
+const router = createHttpRouter({
+    '/api/users': (req, res) => res.json([]),
+    '/api/admin': {
+        GET: {
+            handler: (req, res) => res.json({ admin: true }),
+            middlewares: [adminAuthMiddleware]  // Route-level middleware
+        }
+    }
+}, {
+    middlewares: [requestLogger(), bodyLimit(1024 * 1024)],  // Global middleware
+    timeout: 30000  // Global timeout 30 seconds
+})
+```
+
+## Request Timeout
+
+### Global Timeout
+
+```typescript
+import { createHttpRouter } from '@esengine/server'
+
+const router = createHttpRouter({
+    '/api/data': async (req, res) => {
+        // If processing exceeds 30 seconds, auto-return 408 Request Timeout
+        await someSlowOperation()
+        res.json({ data: 'result' })
+    }
+}, {
+    timeout: 30000  // 30 seconds
+})
+```
+
+### Route-level Timeout
+
+```typescript
+const router = createHttpRouter({
+    '/api/quick': (req, res) => res.json({ fast: true }),
+
+    '/api/slow': {
+        POST: {
+            handler: async (req, res) => {
+                await verySlowOperation()
+                res.json({ done: true })
+            },
+            timeout: 120000  // This route allows 2 minutes
+        }
+    }
+}, {
+    timeout: 10000  // Global 10 seconds (overridden by route-level)
+})
+```
+
+## Best Practices
+
+1. **Use defineHttp** - Get better type hints and code organization
+2. **Unified Error Handling** - Use `res.error()` to return consistent error format
+3. **Enable CORS** - Required for frontend-backend separation
+4. **Directory Organization** - Organize HTTP route files by functional modules
+5. **Validate Input** - Always validate `req.body` and `req.query` content
+6. **Status Code Standards** - Follow HTTP status code conventions (200, 201, 400, 401, 404, 500, etc.)
+7. **Use Middleware** - Implement cross-cutting concerns like auth, logging, rate limiting via middleware
+8. **Set Timeouts** - Prevent slow requests from blocking the server

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

@@ -147,6 +147,7 @@ service.on('chat', (data) => {
 
 - [Client Usage](/en/modules/network/client/) - NetworkPlugin, components and systems
 - [Server Side](/en/modules/network/server/) - GameServer and Room management
+- [Distributed Rooms](/en/modules/network/distributed/) - Multi-server room management and player routing
 - [State Sync](/en/modules/network/sync/) - Interpolation and snapshot buffering
 - [Client Prediction](/en/modules/network/prediction/) - Input prediction and server reconciliation
 - [Area of Interest (AOI)](/en/modules/network/aoi/) - View filtering and bandwidth optimization

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

@@ -79,10 +79,33 @@ await server.start()
 | `tickRate` | `number` | `20` | Global tick rate (Hz) |
 | `apiDir` | `string` | `'src/api'` | API handlers directory |
 | `msgDir` | `string` | `'src/msg'` | Message handlers directory |
+| `httpDir` | `string` | `'src/http'` | HTTP routes directory |
+| `httpPrefix` | `string` | `'/api'` | HTTP routes prefix |
+| `cors` | `boolean \| CorsOptions` | - | CORS configuration |
 | `onStart` | `(port) => void` | - | Start callback |
 | `onConnect` | `(conn) => void` | - | Connection callback |
 | `onDisconnect` | `(conn) => void` | - | Disconnect callback |
 
+## HTTP Routing
+
+Supports HTTP API sharing the same port with WebSocket, ideal for login, registration, and similar scenarios.
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    httpDir: './src/http',   // HTTP routes directory
+    httpPrefix: '/api',       // Route prefix
+    cors: true,
+
+    // Or inline definition
+    http: {
+        '/health': (req, res) => res.json({ status: 'ok' })
+    }
+})
+```
+
+> For detailed documentation, see [HTTP Routing](/en/modules/network/http)
+
 ## Room System
 
 Room is the base class for game rooms, managing players and game state.
@@ -243,6 +266,122 @@ class GameRoom extends Room {
 }
 ```
 
+## Schema Validation
+
+Use the built-in Schema validation system for runtime type validation:
+
+### Basic Usage
+
+```typescript
+import { s, defineApiWithSchema } from '@esengine/server'
+
+// Define schema
+const MoveSchema = s.object({
+    x: s.number(),
+    y: s.number(),
+    speed: s.number().optional()
+})
+
+// Auto type inference
+type Move = s.infer<typeof MoveSchema>  // { x: number; y: number; speed?: number }
+
+// Use schema to define API (auto validation)
+export default defineApiWithSchema(MoveSchema, {
+    handler(req, ctx) {
+        // req is validated, type-safe
+        console.log(req.x, req.y)
+    }
+})
+```
+
+### Validator Types
+
+| Type | Example | Description |
+|------|---------|-------------|
+| `s.string()` | `s.string().min(1).max(50)` | String with length constraints |
+| `s.number()` | `s.number().min(0).int()` | Number with range and integer constraints |
+| `s.boolean()` | `s.boolean()` | Boolean |
+| `s.literal()` | `s.literal('admin')` | Literal type |
+| `s.object()` | `s.object({ name: s.string() })` | Object |
+| `s.array()` | `s.array(s.number())` | Array |
+| `s.enum()` | `s.enum(['a', 'b'] as const)` | Enum |
+| `s.union()` | `s.union([s.string(), s.number()])` | Union type |
+| `s.record()` | `s.record(s.any())` | Record type |
+
+### Modifiers
+
+```typescript
+// Optional field
+s.string().optional()
+
+// Default value
+s.number().default(0)
+
+// Nullable
+s.string().nullable()
+
+// String validation
+s.string().min(1).max(100).email().url().regex(/^[a-z]+$/)
+
+// Number validation
+s.number().min(0).max(100).int().positive()
+
+// Array validation
+s.array(s.string()).min(1).max(10).nonempty()
+
+// Object validation
+s.object({ ... }).strict()  // No extra fields allowed
+s.object({ ... }).partial() // All fields optional
+s.object({ ... }).pick('name', 'age')  // Pick fields
+s.object({ ... }).omit('password')     // Omit fields
+```
+
+### Message Validation
+
+```typescript
+import { s, defineMsgWithSchema } from '@esengine/server'
+
+const InputSchema = s.object({
+    keys: s.array(s.string()),
+    timestamp: s.number()
+})
+
+export default defineMsgWithSchema(InputSchema, {
+    handler(msg, ctx) {
+        // msg is validated
+        console.log(msg.keys, msg.timestamp)
+    }
+})
+```
+
+### Manual Validation
+
+```typescript
+import { s, parse, safeParse, createGuard } from '@esengine/server'
+
+const UserSchema = s.object({
+    name: s.string(),
+    age: s.number().int().min(0)
+})
+
+// Throws on error
+const user = parse(UserSchema, data)
+
+// Returns result object
+const result = safeParse(UserSchema, data)
+if (result.success) {
+    console.log(result.data)
+} else {
+    console.error(result.error)
+}
+
+// Type guard
+const isUser = createGuard(UserSchema)
+if (isUser(data)) {
+    // data is User type
+}
+```
+
 ## Protocol Definition
 
 Define shared types in `src/shared/protocol.ts`:

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/en/modules/transaction/storage.md

@@ -125,23 +125,24 @@ tx:data:{key}           - Business data
 
 ## MongoStorage
 
-MongoDB storage, suitable for scenarios requiring persistence and complex queries. Uses factory pattern with lazy connection.
+MongoDB storage, suitable for scenarios requiring persistence and complex queries. Uses shared connection from `@esengine/database-drivers`.
 
 ```typescript
-import { MongoClient } from 'mongodb';
-import { MongoStorage } from '@esengine/transaction';
+import { createMongoConnection } from '@esengine/database-drivers';
+import { createMongoStorage, TransactionManager } from '@esengine/transaction';
 
-// Factory pattern: lazy connection, connects on first operation
-const storage = new MongoStorage({
-    factory: async () => {
-        const client = new MongoClient('mongodb://localhost:27017');
-        await client.connect();
-        return client;
-    },
-    database: 'game',
-    transactionCollection: 'transactions',  // Transaction log collection
-    dataCollection: 'transaction_data',     // Business data collection
-    lockCollection: 'transaction_locks',    // Lock collection
+// Create shared connection
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+});
+await mongo.connect();
+
+// Create storage using shared connection
+const storage = createMongoStorage(mongo, {
+    transactionCollection: 'transactions',  // Transaction log collection (optional)
+    dataCollection: 'transaction_data',     // Business data collection (optional)
+    lockCollection: 'transaction_locks',    // Lock collection (optional)
 });
 
 // Create indexes (run on first startup)
@@ -149,11 +150,14 @@ await storage.ensureIndexes();
 
 const manager = new TransactionManager({ storage });
 
-// Close connection when done
+// Close storage (does not close shared connection)
 await storage.close();
 
-// Or use await using for automatic cleanup (TypeScript 5.2+)
-await using storage = new MongoStorage({ ... });
+// Shared connection can continue to be used by other modules
+const userRepo = new UserRepository(mongo);  // @esengine/database
+
+// Finally close the shared connection
+await mongo.disconnect();
 ```
 
 ### Characteristics

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/behavior-tree/custom-actions.md

@@ -606,6 +606,107 @@ export class RetryDecorator implements INodeExecutor {
 }
 ```
 
+## 在代码中使用自定义执行器
+
+定义了自定义执行器后，可以通过 `BehaviorTreeBuilder` 的 `.action()` 和 `.condition()` 方法在代码中使用：
+
+### 使用 action() 方法
+
+```typescript
+import { BehaviorTreeBuilder, BehaviorTreeStarter } from '@esengine/behavior-tree';
+
+// 使用自定义执行器构建行为树
+const tree = BehaviorTreeBuilder.create('CombatAI')
+    .defineBlackboardVariable('health', 100)
+    .defineBlackboardVariable('target', null)
+    .selector('Root')
+        .sequence('AttackSequence')
+            // 使用自定义动作 - implementationType 匹配装饰器中的定义
+            .action('AttackAction', 'Attack', { damage: 25 })
+            .action('MoveToPosition', 'Chase', { speed: 10 })
+        .end()
+        .action('DelayAction', 'Idle', { duration: 1.0 })
+    .end()
+    .build();
+
+// 启动行为树
+const entity = scene.createEntity('Enemy');
+BehaviorTreeStarter.start(entity, tree);
+```
+
+### 使用 condition() 方法
+
+```typescript
+const tree = BehaviorTreeBuilder.create('AI')
+    .selector('Root')
+        .sequence('AttackBranch')
+            // 使用自定义条件
+            .condition('CheckHealth', 'IsHealthy', { threshold: 50, operator: 'greater' })
+            .action('AttackAction', 'Attack')
+        .end()
+    .end()
+    .build();
+```
+
+### Builder 方法对照表
+
+| 方法 | 说明 | 使用场景 |
+|------|------|----------|
+| `.action(type, name?, config?)` | 使用自定义动作执行器 | 自定义 Action 类 |
+| `.condition(type, name?, config?)` | 使用自定义条件执行器 | 自定义 Condition 类 |
+| `.executeAction(name)` | 调用黑板函数 `action_{name}` | 简单逻辑、快速原型 |
+| `.executeCondition(name)` | 调用黑板函数 `condition_{name}` | 简单条件判断 |
+
+### 完整示例
+
+```typescript
+import {
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter,
+    NodeExecutorMetadata,
+    INodeExecutor,
+    NodeExecutionContext,
+    TaskStatus,
+    NodeType,
+    BindingHelper
+} from '@esengine/behavior-tree';
+
+// 1. 定义自定义执行器
+@NodeExecutorMetadata({
+    implementationType: 'AttackAction',
+    nodeType: NodeType.Action,
+    displayName: '攻击',
+    category: 'Combat',
+    configSchema: {
+        damage: { type: 'number', default: 10, supportBinding: true }
+    }
+})
+class AttackAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const damage = BindingHelper.getValue<number>(context, 'damage', 10);
+        console.log(`执行攻击，造成 ${damage} 点伤害！`);
+        return TaskStatus.Success;
+    }
+}
+
+// 2. 构建行为树
+const enemyAI = BehaviorTreeBuilder.create('EnemyAI')
+    .defineBlackboardVariable('health', 100)
+    .defineBlackboardVariable('target', null)
+    .selector('MainBehavior')
+        .sequence('AttackBranch')
+            .condition('CheckHealth', 'HasEnoughHealth', { threshold: 20, operator: 'greater' })
+            .action('AttackAction', 'Attack', { damage: 50 })
+        .end()
+        .log('逃跑', 'Flee')
+    .end()
+    .build();
+
+// 3. 启动行为树
+const entity = scene.createEntity('Enemy');
+BehaviorTreeStarter.start(entity, enemyAI);
+```
+
 ## 注册执行器
 
 ### 自动注册

docs/src/content/docs/modules/blueprint/custom-nodes.md

@@ -28,13 +28,13 @@ const MyNodeTemplate: BlueprintNodeTemplate = {
 ## 实现节点执行器
 
 ```typescript
-import { INodeExecutor, RegisterNode } from '@esengine/blueprint';
+import { INodeExecutor, RegisterNode, BlueprintNode, ExecutionContext, ExecutionResult } from '@esengine/blueprint';
 
 @RegisterNode(MyNodeTemplate)
 class MyNodeExecutor implements INodeExecutor {
     execute(node: BlueprintNode, context: ExecutionContext): ExecutionResult {
-        // 获取输入
-        const value = context.getInput<number>(node.id, 'value');
+        // 获取输入（使用 evaluateInput）
+        const value = context.evaluateInput(node.id, 'value', 0) as number;
 
         // 执行逻辑
         const result = value * 2;
@@ -100,29 +100,58 @@ const PureNodeTemplate: BlueprintNodeTemplate = {
 };
 ```
 
-## 实际示例：输入处理节点
+## 实际示例：ECS 组件操作节点
 
 ```typescript
-const InputMoveTemplate: BlueprintNodeTemplate = {
-    type: 'InputMove',
-    title: 'Get Movement Input',
-    category: 'input',
-    inputs: [],
-    outputs: [
-        { name: 'direction', type: 'vector2', direction: 'output' }
+import type { Entity } from '@esengine/ecs-framework';
+import { BlueprintNodeTemplate, BlueprintNode } from '@esengine/blueprint';
+import { ExecutionContext, ExecutionResult } from '@esengine/blueprint';
+import { INodeExecutor, RegisterNode } from '@esengine/blueprint';
+
+// 自定义治疗节点
+const HealEntityTemplate: BlueprintNodeTemplate = {
+    type: 'HealEntity',
+    title: 'Heal Entity',
+    category: 'gameplay',
+    color: '#22aa22',
+    description: 'Heal an entity with HealthComponent',
+    keywords: ['heal', 'health', 'restore'],
+    menuPath: ['Gameplay', 'Combat', 'Heal Entity'],
+    inputs: [
+        { name: 'exec', type: 'exec', displayName: '' },
+        { name: 'entity', type: 'entity', displayName: 'Target' },
+        { name: 'amount', type: 'float', displayName: 'Amount', defaultValue: 10 }
     ],
-    isPure: true
+    outputs: [
+        { name: 'exec', type: 'exec', displayName: '' },
+        { name: 'newHealth', type: 'float', displayName: 'New Health' }
+    ]
 };
 
-@RegisterNode(InputMoveTemplate)
-class InputMoveExecutor implements INodeExecutor {
+@RegisterNode(HealEntityTemplate)
+class HealEntityExecutor implements INodeExecutor {
     execute(node: BlueprintNode, context: ExecutionContext): ExecutionResult {
-        const input = context.scene.services.get(InputServiceToken);
-        const direction = {
-            x: input.getAxis('horizontal'),
-            y: input.getAxis('vertical')
-        };
-        return { outputs: { direction } };
+        const entity = context.evaluateInput(node.id, 'entity', context.entity) as Entity;
+        const amount = context.evaluateInput(node.id, 'amount', 10) as number;
+
+        if (!entity || entity.isDestroyed) {
+            return { outputs: { newHealth: 0 }, nextExec: 'exec' };
+        }
+
+        // 获取 HealthComponent
+        const health = entity.components.find(c =>
+            (c.constructor as any).__componentName__ === 'Health'
+        ) as any;
+
+        if (health) {
+            health.current = Math.min(health.current + amount, health.max);
+            return {
+                outputs: { newHealth: health.current },
+                nextExec: 'exec'
+            };
+        }
+
+        return { outputs: { newHealth: 0 }, nextExec: 'exec' };
     }
 }
 ```

docs/src/content/docs/modules/blueprint/examples.md

@@ -3,85 +3,127 @@ title: "实际示例"
 description: "ECS 集成和最佳实践"
 ---
 
-## 玩家控制蓝图
+## 完整游戏集成示例
 
 ```typescript
-// 定义输入处理节点
-const InputMoveTemplate: BlueprintNodeTemplate = {
-    type: 'InputMove',
-    title: 'Get Movement Input',
-    category: 'input',
-    inputs: [],
-    outputs: [
-        { name: 'direction', type: 'vector2', direction: 'output' }
-    ],
-    isPure: true
-};
+import { Scene, Core, Component, ECSComponent } from '@esengine/ecs-framework';
+import {
+    BlueprintSystem,
+    BlueprintComponent,
+    BlueprintExpose,
+    BlueprintProperty,
+    BlueprintMethod
+} from '@esengine/blueprint';
 
-@RegisterNode(InputMoveTemplate)
-class InputMoveExecutor implements INodeExecutor {
-    execute(node: BlueprintNode, context: ExecutionContext): ExecutionResult {
-        const input = context.scene.services.get(InputServiceToken);
-        const direction = {
-            x: input.getAxis('horizontal'),
-            y: input.getAxis('vertical')
-        };
-        return { outputs: { direction } };
+// 1. 定义游戏组件
+@ECSComponent('Player')
+@BlueprintExpose({ displayName: '玩家', category: 'gameplay' })
+export class PlayerComponent extends Component {
+    @BlueprintProperty({ displayName: '移动速度', type: 'float' })
+    moveSpeed: number = 5;
+
+    @BlueprintProperty({ displayName: '分数', type: 'int' })
+    score: number = 0;
+
+    @BlueprintMethod({ displayName: '增加分数' })
+    addScore(points: number): void {
+        this.score += points;
     }
 }
+
+@ECSComponent('Health')
+@BlueprintExpose({ displayName: '生命值', category: 'gameplay' })
+export class HealthComponent extends Component {
+    @BlueprintProperty({ displayName: '当前生命值' })
+    current: number = 100;
+
+    @BlueprintProperty({ displayName: '最大生命值' })
+    max: number = 100;
+
+    @BlueprintMethod({ displayName: '治疗' })
+    heal(amount: number): void {
+        this.current = Math.min(this.current + amount, this.max);
+    }
+
+    @BlueprintMethod({ displayName: '受伤' })
+    takeDamage(amount: number): boolean {
+        this.current -= amount;
+        return this.current <= 0;
+    }
+}
+
+// 2. 初始化游戏
+async function initGame() {
+    const scene = new Scene();
+
+    // 添加蓝图系统
+    scene.addSystem(new BlueprintSystem());
+
+    Core.setScene(scene);
+
+    // 3. 创建玩家
+    const player = scene.createEntity('Player');
+    player.addComponent(new PlayerComponent());
+    player.addComponent(new HealthComponent());
+
+    // 添加蓝图控制
+    const blueprint = new BlueprintComponent();
+    blueprint.blueprintAsset = await loadBlueprintAsset('player.bp');
+    player.addComponent(blueprint);
+}
 ```
 
-## 状态切换逻辑
+## 自定义节点示例
 
 ```typescript
-// 在蓝图中实现状态机逻辑
-const stateBlueprint = createEmptyBlueprint('PlayerState');
+import type { Entity } from '@esengine/ecs-framework';
+import {
+    BlueprintNodeTemplate,
+    BlueprintNode,
+    ExecutionContext,
+    ExecutionResult,
+    INodeExecutor,
+    RegisterNode
+} from '@esengine/blueprint';
 
-// 添加状态变量
-stateBlueprint.variables.push({
-    name: 'currentState',
-    type: 'string',
-    defaultValue: 'idle',
-    scope: 'instance'
-});
-
-// 在 Tick 事件中检查状态转换
-// ... 通过节点连接实现
-```
-
-## 伤害处理系统
-
-```typescript
 // 自定义伤害节点
 const ApplyDamageTemplate: BlueprintNodeTemplate = {
     type: 'ApplyDamage',
     title: 'Apply Damage',
     category: 'combat',
+    color: '#aa2222',
+    description: '对带有 Health 组件的实体造成伤害',
+    keywords: ['damage', 'hurt', 'attack'],
+    menuPath: ['Combat', 'Apply Damage'],
     inputs: [
-        { name: 'exec', type: 'exec', direction: 'input', isExec: true },
-        { name: 'target', type: 'entity', direction: 'input' },
-        { name: 'amount', type: 'number', direction: 'input', defaultValue: 10 }
+        { name: 'exec', type: 'exec', displayName: '' },
+        { name: 'target', type: 'entity', displayName: '目标' },
+        { name: 'amount', type: 'float', displayName: '伤害量', defaultValue: 10 }
     ],
     outputs: [
-        { name: 'exec', type: 'exec', direction: 'output', isExec: true },
-        { name: 'killed', type: 'boolean', direction: 'output' }
+        { name: 'exec', type: 'exec', displayName: '' },
+        { name: 'killed', type: 'bool', displayName: '已击杀' }
     ]
 };
 
 @RegisterNode(ApplyDamageTemplate)
 class ApplyDamageExecutor implements INodeExecutor {
     execute(node: BlueprintNode, context: ExecutionContext): ExecutionResult {
-        const target = context.getInput<Entity>(node.id, 'target');
-        const amount = context.getInput<number>(node.id, 'amount');
+        const target = context.evaluateInput(node.id, 'target', context.entity) as Entity;
+        const amount = context.evaluateInput(node.id, 'amount', 10) as number;
+
+        if (!target || target.isDestroyed) {
+            return { outputs: { killed: false }, nextExec: 'exec' };
+        }
+
+        const health = target.components.find(c =>
+            (c.constructor as any).__componentName__ === 'Health'
+        ) as any;
 
-        const health = target.getComponent(HealthComponent);
         if (health) {
             health.current -= amount;
             const killed = health.current <= 0;
-            return {
-                outputs: { killed },
-                nextExec: 'exec'
-            };
+            return { outputs: { killed }, nextExec: 'exec' };
         }
 
         return { outputs: { killed: false }, nextExec: 'exec' };
@@ -89,25 +131,6 @@ class ApplyDamageExecutor implements INodeExecutor {
 }
 ```
 
-## 技能冷却系统
-
-```typescript
-// 冷却检查节点
-const CheckCooldownTemplate: BlueprintNodeTemplate = {
-    type: 'CheckCooldown',
-    title: 'Check Cooldown',
-    category: 'ability',
-    inputs: [
-        { name: 'skillId', type: 'string', direction: 'input' }
-    ],
-    outputs: [
-        { name: 'ready', type: 'boolean', direction: 'output' },
-        { name: 'remaining', type: 'number', direction: 'output' }
-    ],
-    isPure: true
-};
-```
-
 ## 最佳实践
 
 ### 1. 使用片段复用逻辑
@@ -151,7 +174,8 @@ vm.maxStepsPerFrame = 1000;
 
 ```typescript
 // 启用调试模式查看执行日志
-vm.debug = true;
+const blueprint = entity.getComponent(BlueprintComponent);
+blueprint.debug = true;
 
 // 使用 Print 节点输出中间值
 // 在编辑器中设置断点

docs/src/content/docs/modules/blueprint/index.md

@@ -1,9 +1,9 @@
 ---
 title: "蓝图可视化脚本 (Blueprint)"
-description: "完整的可视化脚本系统"
+description: "与 ECS 框架深度集成的可视化脚本系统"
 ---
 
-`@esengine/blueprint` 提供了一个功能完整的可视化脚本系统，支持节点式编程、事件驱动和蓝图组合。
+`@esengine/blueprint` 提供与 ECS 框架深度集成的可视化脚本系统，支持通过节点式编程控制实体行为。
 
 ## 安装
 
@@ -11,104 +11,141 @@ description: "完整的可视化脚本系统"
 npm install @esengine/blueprint
 ```
 
+## 核心特性
+
+- **ECS 深度集成** - 内置 Entity、Component 操作节点
+- **组件自动节点生成** - 使用装饰器标记组件，自动生成 Get/Set/Call 节点
+- **运行时蓝图执行** - 高效的虚拟机执行蓝图逻辑
+
 ## 快速开始
 
+### 1. 添加蓝图系统
+
+```typescript
+import { Scene, Core } from '@esengine/ecs-framework';
+import { BlueprintSystem } from '@esengine/blueprint';
+
+// 创建场景并添加蓝图系统
+const scene = new Scene();
+scene.addSystem(new BlueprintSystem());
+
+// 设置场景
+Core.setScene(scene);
+```
+
+### 2. 为实体添加蓝图
+
+```typescript
+import { BlueprintComponent } from '@esengine/blueprint';
+
+// 创建实体
+const player = scene.createEntity('Player');
+
+// 添加蓝图组件
+const blueprint = new BlueprintComponent();
+blueprint.blueprintAsset = await loadBlueprintAsset('player.bp');
+blueprint.autoStart = true;
+player.addComponent(blueprint);
+```
+
+### 3. 标记组件（自动生成蓝图节点）
+
 ```typescript
 import {
-    createBlueprintSystem,
-    createBlueprintComponentData,
-    NodeRegistry,
-    RegisterNode
+    BlueprintExpose,
+    BlueprintProperty,
+    BlueprintMethod
 } from '@esengine/blueprint';
+import { Component, ECSComponent } from '@esengine/ecs-framework';
 
-// 创建蓝图系统
-const blueprintSystem = createBlueprintSystem(scene);
+@ECSComponent('Health')
+@BlueprintExpose({ displayName: '生命值', category: 'gameplay' })
+export class HealthComponent extends Component {
+    @BlueprintProperty({ displayName: '当前生命值', type: 'float' })
+    current: number = 100;
 
-// 加载蓝图资产
-const blueprint = await loadBlueprintAsset('player.bp');
+    @BlueprintProperty({ displayName: '最大生命值', type: 'float' })
+    max: number = 100;
 
-// 创建蓝图组件数据
-const componentData = createBlueprintComponentData();
-componentData.blueprintAsset = blueprint;
+    @BlueprintMethod({
+        displayName: '治疗',
+        params: [{ name: 'amount', type: 'float' }]
+    })
+    heal(amount: number): void {
+        this.current = Math.min(this.current + amount, this.max);
+    }
 
-// 在游戏循环中更新
-function gameLoop(dt: number) {
-    blueprintSystem.process(entities, dt);
+    @BlueprintMethod({ displayName: '受伤' })
+    takeDamage(amount: number): boolean {
+        this.current -= amount;
+        return this.current <= 0;
+    }
 }
 ```
 
-## 核心概念
+标记后，蓝图编辑器中会自动出现以下节点：
+- **Get Health** - 获取 Health 组件
+- **Get 当前生命值** - 获取 current 属性
+- **Set 当前生命值** - 设置 current 属性
+- **治疗** - 调用 heal 方法
+- **受伤** - 调用 takeDamage 方法
 
-### 蓝图资产结构
+## ECS 集成架构
 
-蓝图保存为 `.bp` 文件，包含以下结构：
-
-```typescript
-interface BlueprintAsset {
-    version: number;           // 格式版本
-    type: 'blueprint';         // 资产类型
-    metadata: BlueprintMetadata; // 元数据
-    variables: BlueprintVariable[]; // 变量定义
-    nodes: BlueprintNode[];    // 节点实例
-    connections: BlueprintConnection[]; // 连接
-}
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         Core.update()                        │
+│                              ↓                               │
+│                    Scene.updateSystems()                     │
+│                              ↓                               │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │                  BlueprintSystem                       │  │
+│  │                                                        │  │
+│  │  Matcher.all(BlueprintComponent)                       │  │
+│  │                       ↓                                │  │
+│  │  process(entities) → blueprint.tick() for each entity  │  │
+│  │                       ↓                                │  │
+│  │              BlueprintVM.tick(dt)                      │  │
+│  │                       ↓                                │  │
+│  │         Execute Event/ECS/Flow Nodes                   │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-### 节点类型
-
-节点按功能分为以下类别：
+## 节点类型
 
 | 类别 | 说明 | 颜色 |
 |------|------|------|
-| `event` | 事件节点（入口点） | 红色 |
-| `flow` | 流程控制 | 灰色 |
-| `entity` | 实体操作 | 蓝色 |
-| `component` | 组件访问 | 青色 |
+| `event` | 事件节点（BeginPlay, Tick, EndPlay） | 红色 |
+| `entity` | ECS 实体操作 | 蓝色 |
+| `component` | ECS 组件访问 | 青色 |
+| `flow` | 流程控制（Branch, Sequence, Loop） | 灰色 |
 | `math` | 数学运算 | 绿色 |
-| `logic` | 逻辑运算 | 红色 |
-| `variable` | 变量访问 | 紫色 |
-| `time` | 时间工具 | 青色 |
-| `debug` | 调试工具 | 灰色 |
+| `time` | 时间工具（Delay, GetDeltaTime） | 青色 |
+| `debug` | 调试工具（Print） | 灰色 |
 
-### 引脚类型
+## 蓝图资产结构
 
-节点通过引脚连接：
+蓝图保存为 `.bp` 文件：
 
 ```typescript
-interface BlueprintPinDefinition {
-    name: string;        // 引脚名称
-    type: PinDataType;   // 数据类型
-    direction: 'input' | 'output';
-    isExec?: boolean;    // 是否是执行引脚
-    defaultValue?: unknown;
+interface BlueprintAsset {
+    version: number;
+    type: 'blueprint';
+    metadata: {
+        name: string;
+        description?: string;
+    };
+    variables: BlueprintVariable[];
+    nodes: BlueprintNode[];
+    connections: BlueprintConnection[];
 }
-
-// 支持的数据类型
-type PinDataType =
-    | 'exec'      // 执行流
-    | 'boolean'   // 布尔值
-    | 'number'    // 数字
-    | 'string'    // 字符串
-    | 'vector2'   // 2D 向量
-    | 'vector3'   // 3D 向量
-    | 'entity'    // 实体引用
-    | 'component' // 组件引用
-    | 'any';      // 任意类型
-```
-
-### 变量作用域
-
-```typescript
-type VariableScope =
-    | 'local'     // 每次执行独立
-    | 'instance'  // 每个实体独立
-    | 'global';   // 全局共享
 ```
 
 ## 文档导航
 
-- [虚拟机 API](./vm) - BlueprintVM 执行和上下文
-- [自定义节点](./custom-nodes) - 创建自定义节点
-- [内置节点](./nodes) - 内置节点参考
-- [蓝图组合](./composition) - 片段和组合器
-- [实际示例](./examples) - ECS 集成和最佳实践
+- [虚拟机 API](./vm) - BlueprintVM 与 ECS 集成
+- [ECS 节点参考](./nodes) - 内置 ECS 操作节点
+- [自定义节点](./custom-nodes) - 创建自定义 ECS 节点
+- [蓝图组合](./composition) - 片段复用
+- [实际示例](./examples) - ECS 游戏逻辑示例

docs/src/content/docs/modules/blueprint/nodes.md

@@ -1,107 +1,118 @@
 ---
-title: "内置节点"
-description: "蓝图内置节点参考"
+title: "ECS 节点参考"
+description: "蓝图内置 ECS 操作节点"
 ---
 
 ## 事件节点
 
+生命周期事件，作为蓝图执行的入口点：
+
 | 节点 | 说明 |
 |------|------|
 | `EventBeginPlay` | 蓝图启动时触发 |
-| `EventTick` | 每帧触发 |
+| `EventTick` | 每帧触发，接收 deltaTime |
 | `EventEndPlay` | 蓝图停止时触发 |
-| `EventCollision` | 碰撞时触发 |
-| `EventInput` | 输入事件触发 |
-| `EventTimer` | 定时器触发 |
-| `EventMessage` | 自定义消息触发 |
 
-## 流程控制节点
+## 实体节点 (Entity)
+
+操作 ECS 实体：
+
+| 节点 | 说明 | 类型 |
+|------|------|------|
+| `Get Self` | 获取拥有此蓝图的实体 | 纯节点 |
+| `Create Entity` | 在场景中创建新实体 | 执行节点 |
+| `Destroy Entity` | 销毁指定实体 | 执行节点 |
+| `Destroy Self` | 销毁自身实体 | 执行节点 |
+| `Is Valid` | 检查实体是否有效 | 纯节点 |
+| `Get Entity Name` | 获取实体名称 | 纯节点 |
+| `Set Entity Name` | 设置实体名称 | 执行节点 |
+| `Get Entity Tag` | 获取实体标签 | 纯节点 |
+| `Set Entity Tag` | 设置实体标签 | 执行节点 |
+| `Set Active` | 设置实体激活状态 | 执行节点 |
+| `Is Active` | 检查实体是否激活 | 纯节点 |
+| `Find Entity By Name` | 按名称查找实体 | 纯节点 |
+| `Find Entities By Tag` | 按标签查找所有实体 | 纯节点 |
+| `Get Entity ID` | 获取实体唯一 ID | 纯节点 |
+| `Find Entity By ID` | 按 ID 查找实体 | 纯节点 |
+
+## 组件节点 (Component)
+
+操作 ECS 组件：
+
+| 节点 | 说明 | 类型 |
+|------|------|------|
+| `Has Component` | 检查实体是否有指定组件 | 纯节点 |
+| `Get Component` | 获取实体的组件 | 纯节点 |
+| `Get All Components` | 获取实体所有组件 | 纯节点 |
+| `Remove Component` | 移除组件 | 执行节点 |
+| `Get Component Property` | 获取组件属性值 | 纯节点 |
+| `Set Component Property` | 设置组件属性值 | 执行节点 |
+| `Get Component Type` | 获取组件类型名称 | 纯节点 |
+| `Get Owner Entity` | 从组件获取所属实体 | 纯节点 |
+
+## 流程控制节点 (Flow)
+
+控制执行流程：
 
 | 节点 | 说明 |
 |------|------|
 | `Branch` | 条件分支 (if/else) |
 | `Sequence` | 顺序执行多个输出 |
-| `ForLoop` | 循环执行 |
-| `WhileLoop` | 条件循环 |
-| `DoOnce` | 只执行一次 |
-| `FlipFlop` | 交替执行两个分支 |
+| `For Loop` | 循环执行 |
+| `For Each` | 遍历数组 |
+| `While Loop` | 条件循环 |
+| `Do Once` | 只执行一次 |
+| `Flip Flop` | 交替执行两个分支 |
 | `Gate` | 可开关的执行门 |
 
-## 时间节点
+## 时间节点 (Time)
+
+| 节点 | 说明 | 类型 |
+|------|------|------|
+| `Delay` | 延迟执行 | 执行节点 |
+| `Get Delta Time` | 获取帧间隔时间 | 纯节点 |
+| `Get Time` | 获取运行总时间 | 纯节点 |
+
+## 数学节点 (Math)
 
 | 节点 | 说明 |
 |------|------|
-| `Delay` | 延迟执行 |
-| `GetDeltaTime` | 获取帧间隔 |
-| `GetTime` | 获取运行时间 |
-| `SetTimer` | 设置定时器 |
-| `ClearTimer` | 清除定时器 |
-
-## 数学节点
-
-| 节点 | 说明 |
-|------|------|
-| `Add` | 加法 |
-| `Subtract` | 减法 |
-| `Multiply` | 乘法 |
-| `Divide` | 除法 |
+| `Add` / `Subtract` / `Multiply` / `Divide` | 四则运算 |
 | `Abs` | 绝对值 |
 | `Clamp` | 限制范围 |
 | `Lerp` | 线性插值 |
 | `Min` / `Max` | 最小/最大值 |
-| `Sin` / `Cos` | 三角函数 |
-| `Sqrt` | 平方根 |
-| `Power` | 幂运算 |
 
-## 逻辑节点
+## 调试节点 (Debug)
 
 | 节点 | 说明 |
 |------|------|
-| `And` | 逻辑与 |
-| `Or` | 逻辑或 |
-| `Not` | 逻辑非 |
-| `Equal` | 相等比较 |
-| `NotEqual` | 不等比较 |
-| `Greater` | 大于比较 |
-| `Less` | 小于比较 |
+| `Print` | 输出到控制台 |
 
-## 向量节点
+## 自动生成的组件节点
 
-| 节点 | 说明 |
-|------|------|
-| `MakeVector2` | 创建 2D 向量 |
-| `BreakVector2` | 分解 2D 向量 |
-| `VectorAdd` | 向量加法 |
-| `VectorSubtract` | 向量减法 |
-| `VectorMultiply` | 向量乘法 |
-| `VectorLength` | 向量长度 |
-| `VectorNormalize` | 向量归一化 |
-| `VectorDistance` | 向量距离 |
+使用 `@BlueprintExpose` 装饰器标记的组件会自动生成节点：
 
-## 实体节点
+```typescript
+@ECSComponent('Transform')
+@BlueprintExpose({ displayName: '变换', category: 'core' })
+export class TransformComponent extends Component {
+    @BlueprintProperty({ displayName: 'X 坐标' })
+    x: number = 0;
 
-| 节点 | 说明 |
-|------|------|
-| `GetSelf` | 获取当前实体 |
-| `GetComponent` | 获取组件 |
-| `HasComponent` | 检查组件 |
-| `AddComponent` | 添加组件 |
-| `RemoveComponent` | 移除组件 |
-| `SpawnEntity` | 创建实体 |
-| `DestroyEntity` | 销毁实体 |
+    @BlueprintProperty({ displayName: 'Y 坐标' })
+    y: number = 0;
 
-## 变量节点
+    @BlueprintMethod({ displayName: '移动' })
+    translate(dx: number, dy: number): void {
+        this.x += dx;
+        this.y += dy;
+    }
+}
+```
 
-| 节点 | 说明 |
-|------|------|
-| `GetVariable` | 获取变量值 |
-| `SetVariable` | 设置变量值 |
-
-## 调试节点
-
-| 节点 | 说明 |
-|------|------|
-| `Print` | 打印到控制台 |
-| `DrawDebugLine` | 绘制调试线 |
-| `DrawDebugPoint` | 绘制调试点 |
-| `Breakpoint` | 调试断点 |
+生成的节点：
+- **Get Transform** - 获取 Transform 组件
+- **Get X 坐标** / **Set X 坐标** - 访问 x 属性
+- **Get Y 坐标** / **Set Y 坐标** - 访问 y 属性
+- **移动** - 调用 translate 方法

docs/src/content/docs/modules/blueprint/vm.md

@@ -45,7 +45,7 @@ interface ExecutionContext {
     time: number;               // 总运行时间
 
     // 获取输入值
-    getInput<T>(nodeId: string, pinName: string): T;
+    evaluateInput(nodeId: string, pinName: string, defaultValue: unknown): unknown;
 
     // 设置输出值
     setOutput(nodeId: string, pinName: string, value: unknown): void;
@@ -70,35 +70,33 @@ interface ExecutionResult {
 
 ## 与 ECS 集成
 
-### 使用蓝图系统
+### 使用内置蓝图系统
 
 ```typescript
-import { createBlueprintSystem } from '@esengine/blueprint';
+import { Scene, Core } from '@esengine/ecs-framework';
+import { BlueprintSystem, BlueprintComponent } from '@esengine/blueprint';
 
-class GameScene {
-    private blueprintSystem: BlueprintSystem;
+// 添加蓝图系统到场景
+const scene = new Scene();
+scene.addSystem(new BlueprintSystem());
+Core.setScene(scene);
 
-    initialize() {
-        this.blueprintSystem = createBlueprintSystem(this.scene);
-    }
-
-    update(dt: number) {
-        // 处理所有带蓝图组件的实体
-        this.blueprintSystem.process(this.entities, dt);
-    }
-}
+// 为实体添加蓝图
+const entity = scene.createEntity('Player');
+const blueprint = new BlueprintComponent();
+blueprint.blueprintAsset = await loadBlueprintAsset('player.bp');
+entity.addComponent(blueprint);
 ```
 
 ### 触发蓝图事件
 
 ```typescript
-import { triggerBlueprintEvent, triggerCustomBlueprintEvent } from '@esengine/blueprint';
-
-// 触发内置事件
-triggerBlueprintEvent(entity, 'Collision', { other: otherEntity });
-
-// 触发自定义事件
-triggerCustomBlueprintEvent(entity, 'OnPickup', { item: itemEntity });
+// 从实体获取蓝图组件并触发事件
+const blueprint = entity.getComponent(BlueprintComponent);
+if (blueprint?.vm) {
+    blueprint.vm.triggerEvent('EventCollision', { other: otherEntity });
+    blueprint.vm.triggerCustomEvent('OnPickup', { item: itemEntity });
+}
 ```
 
 ## 序列化

docs/src/content/docs/modules/database-drivers/index.md

@@ -0,0 +1,136 @@
+---
+title: "数据库驱动"
+description: "MongoDB、Redis 等数据库的连接管理和驱动封装"
+---
+
+`@esengine/database-drivers` 是 ESEngine 的数据库连接管理层，提供 MongoDB、Redis 等数据库的统一连接管理。
+
+## 特性
+
+- **连接池管理** - 自动管理连接池，优化资源使用
+- **自动重连** - 连接断开时自动重连
+- **事件通知** - 连接状态变化事件
+- **类型解耦** - 简化接口，不依赖原生驱动类型
+- **共享连接** - 单一连接可供多个模块共享
+
+## 安装
+
+```bash
+npm install @esengine/database-drivers
+```
+
+**对等依赖：**
+```bash
+npm install mongodb    # MongoDB 支持
+npm install ioredis    # Redis 支持
+```
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  @esengine/database-drivers (Layer 1)                           │
+│  ┌─────────────────────┐  ┌─────────────────────┐               │
+│  │   MongoConnection   │  │   RedisConnection   │               │
+│  │   - 连接池管理      │  │   - 自动重连        │               │
+│  │   - 自动重连        │  │   - Key 前缀        │               │
+│  │   - 事件发射器      │  │   - 事件发射器      │               │
+│  └──────────┬──────────┘  └─────────────────────┘               │
+│             │                                                    │
+│  ┌──────────▼──────────┐                                        │
+│  │ IMongoCollection<T> │  ← 类型安全接口                         │
+│  │ (适配器模式)        │    与 mongodb 类型解耦                   │
+│  └─────────────────────┘                                        │
+└─────────────────────────────────────────────────────────────────┘
+            │
+            ▼
+┌───────────────────────┐  ┌───────────────────────┐
+│  @esengine/database   │  │ @esengine/transaction │
+│  (仓库模式)           │  │ (分布式事务)          │
+└───────────────────────┘  └───────────────────────┘
+```
+
+## 快速开始
+
+### MongoDB 连接
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+
+// 创建连接
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game',
+    pool: {
+        minSize: 5,
+        maxSize: 20
+    },
+    autoReconnect: true
+})
+
+// 监听事件
+mongo.on('connected', () => console.log('MongoDB 已连接'))
+mongo.on('disconnected', () => console.log('MongoDB 已断开'))
+mongo.on('error', (e) => console.error('错误:', e.error))
+
+// 建立连接
+await mongo.connect()
+
+// 使用集合
+const users = mongo.collection<User>('users')
+await users.insertOne({ name: 'John', score: 100 })
+
+const user = await users.findOne({ name: 'John' })
+
+// 完成后断开连接
+await mongo.disconnect()
+```
+
+### Redis 连接
+
+```typescript
+import { createRedisConnection } from '@esengine/database-drivers'
+
+const redis = createRedisConnection({
+    host: 'localhost',
+    port: 6379,
+    keyPrefix: 'game:',
+    autoReconnect: true
+})
+
+await redis.connect()
+
+// 基本操作
+await redis.set('session:123', 'data', 3600)  // 带 TTL
+const value = await redis.get('session:123')
+
+await redis.disconnect()
+```
+
+## 服务容器集成
+
+```typescript
+import { ServiceContainer } from '@esengine/ecs-framework'
+import {
+    createMongoConnection,
+    MongoConnectionToken,
+    RedisConnectionToken
+} from '@esengine/database-drivers'
+
+const services = new ServiceContainer()
+
+// 注册连接
+const mongo = createMongoConnection({ uri: '...', database: 'game' })
+await mongo.connect()
+services.register(MongoConnectionToken, mongo)
+
+// 在其他模块中获取
+const connection = services.get(MongoConnectionToken)
+const users = connection.collection('users')
+```
+
+## 文档
+
+- [MongoDB 连接](/modules/database-drivers/mongo/) - MongoDB 连接详细配置
+- [Redis 连接](/modules/database-drivers/redis/) - Redis 连接详细配置
+- [服务令牌](/modules/database-drivers/tokens/) - 依赖注入集成

docs/src/content/docs/modules/database-drivers/mongo.md

@@ -0,0 +1,265 @@
+---
+title: "MongoDB 连接"
+description: "MongoDB 连接管理、连接池、自动重连"
+---
+
+## 配置选项
+
+```typescript
+interface MongoConnectionConfig {
+    /** MongoDB 连接 URI */
+    uri: string
+
+    /** 数据库名称 */
+    database: string
+
+    /** 连接池配置 */
+    pool?: {
+        minSize?: number      // 最小连接数
+        maxSize?: number      // 最大连接数
+        acquireTimeout?: number  // 获取连接超时（毫秒）
+        maxLifetime?: number     // 连接最大生命周期（毫秒）
+    }
+
+    /** 是否自动重连（默认 true） */
+    autoReconnect?: boolean
+
+    /** 重连间隔（毫秒，默认 5000） */
+    reconnectInterval?: number
+
+    /** 最大重连次数（默认 10） */
+    maxReconnectAttempts?: number
+}
+```
+
+## 完整示例
+
+```typescript
+import { createMongoConnection, MongoConnectionToken } from '@esengine/database-drivers'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game',
+    pool: {
+        minSize: 5,
+        maxSize: 20,
+        acquireTimeout: 5000,
+        maxLifetime: 300000
+    },
+    autoReconnect: true,
+    reconnectInterval: 5000,
+    maxReconnectAttempts: 10
+})
+
+// 事件监听
+mongo.on('connected', () => {
+    console.log('MongoDB 已连接')
+})
+
+mongo.on('disconnected', () => {
+    console.log('MongoDB 已断开')
+})
+
+mongo.on('reconnecting', () => {
+    console.log('MongoDB 正在重连...')
+})
+
+mongo.on('reconnected', () => {
+    console.log('MongoDB 重连成功')
+})
+
+mongo.on('error', (event) => {
+    console.error('MongoDB 错误:', event.error)
+})
+
+// 连接
+await mongo.connect()
+
+// 检查状态
+console.log('已连接:', mongo.isConnected())
+console.log('Ping:', await mongo.ping())
+```
+
+## IMongoConnection 接口
+
+```typescript
+interface IMongoConnection {
+    /** 连接 ID */
+    readonly id: string
+
+    /** 连接状态 */
+    readonly state: ConnectionState
+
+    /** 建立连接 */
+    connect(): Promise<void>
+
+    /** 断开连接 */
+    disconnect(): Promise<void>
+
+    /** 检查是否已连接 */
+    isConnected(): boolean
+
+    /** 测试连接 */
+    ping(): Promise<boolean>
+
+    /** 获取类型化集合 */
+    collection<T extends object>(name: string): IMongoCollection<T>
+
+    /** 获取数据库接口 */
+    getDatabase(): IMongoDatabase
+
+    /** 获取原生客户端（高级用法） */
+    getNativeClient(): MongoClientType
+
+    /** 获取原生数据库（高级用法） */
+    getNativeDatabase(): Db
+}
+```
+
+## IMongoCollection 接口
+
+类型安全的集合接口，与原生 MongoDB 类型解耦：
+
+```typescript
+interface IMongoCollection<T extends object> {
+    readonly name: string
+
+    // 查询
+    findOne(filter: object, options?: FindOptions): Promise<T | null>
+    find(filter: object, options?: FindOptions): Promise<T[]>
+    countDocuments(filter?: object): Promise<number>
+
+    // 插入
+    insertOne(doc: T): Promise<InsertOneResult>
+    insertMany(docs: T[]): Promise<InsertManyResult>
+
+    // 更新
+    updateOne(filter: object, update: object): Promise<UpdateResult>
+    updateMany(filter: object, update: object): Promise<UpdateResult>
+    findOneAndUpdate(
+        filter: object,
+        update: object,
+        options?: FindOneAndUpdateOptions
+    ): Promise<T | null>
+
+    // 删除
+    deleteOne(filter: object): Promise<DeleteResult>
+    deleteMany(filter: object): Promise<DeleteResult>
+
+    // 索引
+    createIndex(
+        spec: Record<string, 1 | -1>,
+        options?: IndexOptions
+    ): Promise<string>
+}
+```
+
+## 使用示例
+
+### 基本 CRUD
+
+```typescript
+interface User {
+    id: string
+    name: string
+    email: string
+    score: number
+}
+
+const users = mongo.collection<User>('users')
+
+// 插入
+await users.insertOne({
+    id: '1',
+    name: 'John',
+    email: 'john@example.com',
+    score: 100
+})
+
+// 查询
+const user = await users.findOne({ name: 'John' })
+
+const topUsers = await users.find(
+    { score: { $gte: 100 } },
+    { sort: { score: -1 }, limit: 10 }
+)
+
+// 更新
+await users.updateOne(
+    { id: '1' },
+    { $inc: { score: 10 } }
+)
+
+// 删除
+await users.deleteOne({ id: '1' })
+```
+
+### 批量操作
+
+```typescript
+// 批量插入
+await users.insertMany([
+    { id: '1', name: 'Alice', email: 'alice@example.com', score: 100 },
+    { id: '2', name: 'Bob', email: 'bob@example.com', score: 200 },
+    { id: '3', name: 'Carol', email: 'carol@example.com', score: 150 }
+])
+
+// 批量更新
+await users.updateMany(
+    { score: { $lt: 100 } },
+    { $set: { status: 'inactive' } }
+)
+
+// 批量删除
+await users.deleteMany({ status: 'inactive' })
+```
+
+### 索引管理
+
+```typescript
+// 创建索引
+await users.createIndex({ email: 1 }, { unique: true })
+await users.createIndex({ score: -1 })
+await users.createIndex({ name: 1, score: -1 })
+```
+
+## 与其他模块集成
+
+### 与 @esengine/database 集成
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { UserRepository, createRepository } from '@esengine/database'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+// 使用 UserRepository
+const userRepo = new UserRepository(mongo)
+await userRepo.register({ username: 'john', password: '123456' })
+
+// 使用通用仓库
+const playerRepo = createRepository<Player>(mongo, 'players')
+```
+
+### 与 @esengine/transaction 集成
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { createMongoStorage, TransactionManager } from '@esengine/transaction'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+// 创建事务存储（共享连接）
+const storage = createMongoStorage(mongo)
+await storage.ensureIndexes()
+
+const txManager = new TransactionManager({ storage })
+```

docs/src/content/docs/modules/database-drivers/redis.md

@@ -0,0 +1,228 @@
+---
+title: "Redis 连接"
+description: "Redis 连接管理、自动重连、键前缀"
+---
+
+## 配置选项
+
+```typescript
+interface RedisConnectionConfig {
+    /** Redis 主机 */
+    host?: string
+
+    /** Redis 端口 */
+    port?: number
+
+    /** 认证密码 */
+    password?: string
+
+    /** 数据库编号 */
+    db?: number
+
+    /** 键前缀 */
+    keyPrefix?: string
+
+    /** 是否自动重连（默认 true） */
+    autoReconnect?: boolean
+
+    /** 重连间隔（毫秒，默认 5000） */
+    reconnectInterval?: number
+
+    /** 最大重连次数（默认 10） */
+    maxReconnectAttempts?: number
+}
+```
+
+## 完整示例
+
+```typescript
+import { createRedisConnection, RedisConnectionToken } from '@esengine/database-drivers'
+
+const redis = createRedisConnection({
+    host: 'localhost',
+    port: 6379,
+    password: 'your-password',
+    db: 0,
+    keyPrefix: 'game:',
+    autoReconnect: true,
+    reconnectInterval: 5000,
+    maxReconnectAttempts: 10
+})
+
+// 事件监听
+redis.on('connected', () => {
+    console.log('Redis 已连接')
+})
+
+redis.on('disconnected', () => {
+    console.log('Redis 已断开')
+})
+
+redis.on('error', (event) => {
+    console.error('Redis 错误:', event.error)
+})
+
+// 连接
+await redis.connect()
+
+// 检查状态
+console.log('已连接:', redis.isConnected())
+console.log('Ping:', await redis.ping())
+```
+
+## IRedisConnection 接口
+
+```typescript
+interface IRedisConnection {
+    /** 连接 ID */
+    readonly id: string
+
+    /** 连接状态 */
+    readonly state: ConnectionState
+
+    /** 建立连接 */
+    connect(): Promise<void>
+
+    /** 断开连接 */
+    disconnect(): Promise<void>
+
+    /** 检查是否已连接 */
+    isConnected(): boolean
+
+    /** 测试连接 */
+    ping(): Promise<boolean>
+
+    /** 获取值 */
+    get(key: string): Promise<string | null>
+
+    /** 设置值（可选 TTL，单位秒） */
+    set(key: string, value: string, ttl?: number): Promise<void>
+
+    /** 删除键 */
+    del(key: string): Promise<boolean>
+
+    /** 检查键是否存在 */
+    exists(key: string): Promise<boolean>
+
+    /** 设置过期时间（秒） */
+    expire(key: string, seconds: number): Promise<boolean>
+
+    /** 获取剩余过期时间（秒） */
+    ttl(key: string): Promise<number>
+
+    /** 获取原生客户端（高级用法） */
+    getNativeClient(): Redis
+}
+```
+
+## 使用示例
+
+### 基本操作
+
+```typescript
+// 设置值
+await redis.set('user:1:name', 'John')
+
+// 设置带过期时间的值（1 小时）
+await redis.set('session:abc123', 'user-data', 3600)
+
+// 获取值
+const name = await redis.get('user:1:name')
+
+// 检查键是否存在
+const exists = await redis.exists('user:1:name')
+
+// 删除键
+await redis.del('user:1:name')
+
+// 获取剩余过期时间
+const ttl = await redis.ttl('session:abc123')
+```
+
+### 键前缀
+
+配置 `keyPrefix` 后，所有操作自动添加前缀：
+
+```typescript
+const redis = createRedisConnection({
+    host: 'localhost',
+    keyPrefix: 'game:'
+})
+
+// 实际操作的键是 'game:user:1'
+await redis.set('user:1', 'data')
+
+// 实际查询的键是 'game:user:1'
+const data = await redis.get('user:1')
+```
+
+### 高级操作
+
+使用原生客户端进行高级操作：
+
+```typescript
+const client = redis.getNativeClient()
+
+// 使用 Pipeline
+const pipeline = client.pipeline()
+pipeline.set('key1', 'value1')
+pipeline.set('key2', 'value2')
+pipeline.set('key3', 'value3')
+await pipeline.exec()
+
+// 使用事务
+const multi = client.multi()
+multi.incr('counter')
+multi.get('counter')
+const results = await multi.exec()
+
+// 使用 Lua 脚本
+const result = await client.eval(
+    `return redis.call('get', KEYS[1])`,
+    1,
+    'mykey'
+)
+```
+
+## 与事务系统集成
+
+```typescript
+import { createRedisConnection } from '@esengine/database-drivers'
+import { RedisStorage, TransactionManager } from '@esengine/transaction'
+
+const redis = createRedisConnection({
+    host: 'localhost',
+    port: 6379,
+    keyPrefix: 'tx:'
+})
+await redis.connect()
+
+// 创建事务存储
+const storage = new RedisStorage({
+    factory: () => redis.getNativeClient(),
+    prefix: 'tx:'
+})
+
+const txManager = new TransactionManager({ storage })
+```
+
+## 连接状态
+
+```typescript
+type ConnectionState =
+    | 'disconnected'  // 未连接
+    | 'connecting'    // 连接中
+    | 'connected'     // 已连接
+    | 'disconnecting' // 断开中
+    | 'error'         // 错误状态
+```
+
+## 事件
+
+| 事件 | 描述 |
+|------|------|
+| `connected` | 连接成功 |
+| `disconnected` | 连接断开 |
+| `reconnecting` | 正在重连 |
+| `reconnected` | 重连成功 |
+| `error` | 发生错误 |

docs/src/content/docs/modules/database/index.md

@@ -0,0 +1,140 @@
+---
+title: "数据库仓库"
+description: "Repository 模式的数据库操作层，支持 CRUD、分页、软删除"
+---
+
+`@esengine/database` 是 ESEngine 的数据库操作层，基于 Repository 模式提供类型安全的 CRUD 操作。
+
+## 特性
+
+- **Repository 模式** - 泛型 CRUD 操作，类型安全
+- **分页查询** - 内置分页支持
+- **软删除** - 可选的软删除与恢复
+- **用户管理** - 开箱即用的 UserRepository
+- **密码安全** - 使用 scrypt 的密码哈希工具
+
+## 安装
+
+```bash
+npm install @esengine/database @esengine/database-drivers
+```
+
+## 快速开始
+
+### 基本仓库
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { Repository, createRepository } from '@esengine/database'
+
+// 定义实体
+interface Player {
+    id: string
+    name: string
+    score: number
+    createdAt: Date
+    updatedAt: Date
+}
+
+// 创建连接
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+// 创建仓库
+const playerRepo = createRepository<Player>(mongo, 'players')
+
+// CRUD 操作
+const player = await playerRepo.create({
+    name: 'John',
+    score: 0
+})
+
+const found = await playerRepo.findById(player.id)
+
+await playerRepo.update(player.id, { score: 100 })
+
+await playerRepo.delete(player.id)
+```
+
+### 自定义仓库
+
+```typescript
+import { Repository, BaseEntity } from '@esengine/database'
+import type { IMongoConnection } from '@esengine/database-drivers'
+
+interface Player extends BaseEntity {
+    name: string
+    score: number
+    rank?: string
+}
+
+class PlayerRepository extends Repository<Player> {
+    constructor(connection: IMongoConnection) {
+        super(connection, 'players')
+    }
+
+    async findTopPlayers(limit: number = 10): Promise<Player[]> {
+        return this.findMany({
+            sort: { score: 'desc' },
+            limit
+        })
+    }
+
+    async findByRank(rank: string): Promise<Player[]> {
+        return this.findMany({
+            where: { rank }
+        })
+    }
+
+    async incrementScore(playerId: string, amount: number): Promise<Player | null> {
+        const player = await this.findById(playerId)
+        if (!player) return null
+        return this.update(playerId, { score: player.score + amount })
+    }
+}
+
+// 使用
+const playerRepo = new PlayerRepository(mongo)
+const topPlayers = await playerRepo.findTopPlayers(5)
+```
+
+### 用户仓库
+
+```typescript
+import { UserRepository } from '@esengine/database'
+
+const userRepo = new UserRepository(mongo)
+
+// 注册新用户
+const user = await userRepo.register({
+    username: 'john',
+    password: 'securePassword123',
+    email: 'john@example.com'
+})
+
+// 认证
+const authenticated = await userRepo.authenticate('john', 'securePassword123')
+if (authenticated) {
+    console.log('登录成功:', authenticated.username)
+}
+
+// 修改密码
+await userRepo.changePassword(user.id, 'securePassword123', 'newPassword456')
+
+// 角色管理
+await userRepo.addRole(user.id, 'admin')
+await userRepo.removeRole(user.id, 'admin')
+
+// 查询用户
+const admins = await userRepo.findByRole('admin')
+const john = await userRepo.findByUsername('john')
+```
+
+## 文档
+
+- [仓库 API](/modules/database/repository/) - Repository 详细 API
+- [用户管理](/modules/database/user/) - UserRepository 用法
+- [查询语法](/modules/database/query/) - 查询条件语法

docs/src/content/docs/modules/database/query.md

@@ -0,0 +1,185 @@
+---
+title: "查询语法"
+description: "查询条件操作符和语法"
+---
+
+## 基本查询
+
+### 精确匹配
+
+```typescript
+await repo.findMany({
+    where: {
+        name: 'John',
+        status: 'active'
+    }
+})
+```
+
+### 使用操作符
+
+```typescript
+await repo.findMany({
+    where: {
+        score: { $gte: 100 },
+        rank: { $in: ['gold', 'platinum'] }
+    }
+})
+```
+
+## 查询操作符
+
+| 操作符 | 描述 | 示例 |
+|--------|------|------|
+| `$eq` | 等于 | `{ score: { $eq: 100 } }` |
+| `$ne` | 不等于 | `{ status: { $ne: 'banned' } }` |
+| `$gt` | 大于 | `{ score: { $gt: 50 } }` |
+| `$gte` | 大于等于 | `{ level: { $gte: 10 } }` |
+| `$lt` | 小于 | `{ age: { $lt: 18 } }` |
+| `$lte` | 小于等于 | `{ price: { $lte: 100 } }` |
+| `$in` | 在数组中 | `{ rank: { $in: ['gold', 'platinum'] } }` |
+| `$nin` | 不在数组中 | `{ status: { $nin: ['banned', 'suspended'] } }` |
+| `$like` | 模式匹配 | `{ name: { $like: '%john%' } }` |
+| `$regex` | 正则匹配 | `{ email: { $regex: '@gmail.com$' } }` |
+
+## 逻辑操作符
+
+### $or
+
+```typescript
+await repo.findMany({
+    where: {
+        $or: [
+            { score: { $gte: 1000 } },
+            { rank: 'legendary' }
+        ]
+    }
+})
+```
+
+### $and
+
+```typescript
+await repo.findMany({
+    where: {
+        $and: [
+            { score: { $gte: 100 } },
+            { score: { $lte: 500 } }
+        ]
+    }
+})
+```
+
+### 组合使用
+
+```typescript
+await repo.findMany({
+    where: {
+        status: 'active',
+        $or: [
+            { rank: 'gold' },
+            { score: { $gte: 1000 } }
+        ]
+    }
+})
+```
+
+## 模式匹配
+
+### $like 语法
+
+- `%` - 匹配任意字符序列
+- `_` - 匹配单个字符
+
+```typescript
+// 以 'John' 开头
+{ name: { $like: 'John%' } }
+
+// 以 'son' 结尾
+{ name: { $like: '%son' } }
+
+// 包含 'oh'
+{ name: { $like: '%oh%' } }
+
+// 第二个字符是 'o'
+{ name: { $like: '_o%' } }
+```
+
+### $regex 语法
+
+使用标准正则表达式：
+
+```typescript
+// 以 'John' 开头（大小写不敏感）
+{ name: { $regex: '^john' } }
+
+// Gmail 邮箱
+{ email: { $regex: '@gmail\\.com$' } }
+
+// 包含数字
+{ username: { $regex: '\\d+' } }
+```
+
+## 排序
+
+```typescript
+await repo.findMany({
+    sort: {
+        score: 'desc',  // 降序
+        name: 'asc'     // 升序
+    }
+})
+```
+
+## 分页
+
+### 使用 limit/offset
+
+```typescript
+// 第一页
+await repo.findMany({
+    limit: 20,
+    offset: 0
+})
+
+// 第二页
+await repo.findMany({
+    limit: 20,
+    offset: 20
+})
+```
+
+### 使用 findPaginated
+
+```typescript
+const result = await repo.findPaginated(
+    { page: 2, pageSize: 20 },
+    { sort: { createdAt: 'desc' } }
+)
+```
+
+## 完整示例
+
+```typescript
+// 查找活跃的金牌玩家，分数在 100-1000 之间
+// 按分数降序排列，取前 10 个
+const players = await repo.findMany({
+    where: {
+        status: 'active',
+        rank: 'gold',
+        score: { $gte: 100, $lte: 1000 }
+    },
+    sort: { score: 'desc' },
+    limit: 10
+})
+
+// 搜索用户名包含 'john' 或邮箱是 gmail 的用户
+const users = await repo.findMany({
+    where: {
+        $or: [
+            { username: { $like: '%john%' } },
+            { email: { $regex: '@gmail\\.com$' } }
+        ]
+    }
+})
+```

docs/src/content/docs/modules/database/repository.md

@@ -0,0 +1,244 @@
+---
+title: "Repository API"
+description: "泛型仓库接口，CRUD 操作、分页、软删除"
+---
+
+## 创建仓库
+
+### 使用工厂函数
+
+```typescript
+import { createRepository } from '@esengine/database'
+
+const playerRepo = createRepository<Player>(mongo, 'players')
+
+// 启用软删除
+const playerRepo = createRepository<Player>(mongo, 'players', true)
+```
+
+### 继承 Repository
+
+```typescript
+import { Repository, BaseEntity } from '@esengine/database'
+
+interface Player extends BaseEntity {
+    name: string
+    score: number
+}
+
+class PlayerRepository extends Repository<Player> {
+    constructor(connection: IMongoConnection) {
+        super(connection, 'players', false)  // 第三个参数：启用软删除
+    }
+
+    // 添加自定义方法
+    async findTopPlayers(limit: number): Promise<Player[]> {
+        return this.findMany({
+            sort: { score: 'desc' },
+            limit
+        })
+    }
+}
+```
+
+## BaseEntity 接口
+
+所有实体必须继承 `BaseEntity`：
+
+```typescript
+interface BaseEntity {
+    id: string
+    createdAt: Date
+    updatedAt: Date
+    deletedAt?: Date  // 软删除时使用
+}
+```
+
+## 查询方法
+
+### findById
+
+```typescript
+const player = await repo.findById('player-123')
+```
+
+### findOne
+
+```typescript
+const player = await repo.findOne({
+    where: { name: 'John' }
+})
+
+const topPlayer = await repo.findOne({
+    sort: { score: 'desc' }
+})
+```
+
+### findMany
+
+```typescript
+// 简单查询
+const players = await repo.findMany({
+    where: { rank: 'gold' }
+})
+
+// 复杂查询
+const players = await repo.findMany({
+    where: {
+        score: { $gte: 100 },
+        rank: { $in: ['gold', 'platinum'] }
+    },
+    sort: { score: 'desc', name: 'asc' },
+    limit: 10,
+    offset: 0
+})
+```
+
+### findPaginated
+
+```typescript
+const result = await repo.findPaginated(
+    { page: 1, pageSize: 20 },
+    {
+        where: { rank: 'gold' },
+        sort: { score: 'desc' }
+    }
+)
+
+console.log(result.data)        // Player[]
+console.log(result.total)       // 总数量
+console.log(result.totalPages)  // 总页数
+console.log(result.hasNext)     // 是否有下一页
+console.log(result.hasPrev)     // 是否有上一页
+```
+
+### count
+
+```typescript
+const count = await repo.count({
+    where: { rank: 'gold' }
+})
+```
+
+### exists
+
+```typescript
+const exists = await repo.exists({
+    where: { email: 'john@example.com' }
+})
+```
+
+## 创建方法
+
+### create
+
+```typescript
+const player = await repo.create({
+    name: 'John',
+    score: 0
+})
+// 自动生成 id, createdAt, updatedAt
+```
+
+### createMany
+
+```typescript
+const players = await repo.createMany([
+    { name: 'Alice', score: 100 },
+    { name: 'Bob', score: 200 },
+    { name: 'Carol', score: 150 }
+])
+```
+
+## 更新方法
+
+### update
+
+```typescript
+const updated = await repo.update('player-123', {
+    score: 200,
+    rank: 'gold'
+})
+// 自动更新 updatedAt
+```
+
+## 删除方法
+
+### delete
+
+```typescript
+// 普通删除
+await repo.delete('player-123')
+
+// 软删除（如果启用）
+// 实际是设置 deletedAt 字段
+```
+
+### deleteMany
+
+```typescript
+const count = await repo.deleteMany({
+    where: { score: { $lt: 10 } }
+})
+```
+
+## 软删除
+
+### 启用软删除
+
+```typescript
+const repo = createRepository<Player>(mongo, 'players', true)
+```
+
+### 查询行为
+
+```typescript
+// 默认排除软删除记录
+const players = await repo.findMany()
+
+// 包含软删除记录
+const allPlayers = await repo.findMany({
+    includeSoftDeleted: true
+})
+```
+
+### 恢复记录
+
+```typescript
+await repo.restore('player-123')
+```
+
+## QueryOptions
+
+```typescript
+interface QueryOptions<T> {
+    /** 查询条件 */
+    where?: WhereCondition<T>
+
+    /** 排序 */
+    sort?: Partial<Record<keyof T, 'asc' | 'desc'>>
+
+    /** 限制数量 */
+    limit?: number
+
+    /** 偏移量 */
+    offset?: number
+
+    /** 包含软删除记录（仅在启用软删除时有效） */
+    includeSoftDeleted?: boolean
+}
+```
+
+## PaginatedResult
+
+```typescript
+interface PaginatedResult<T> {
+    data: T[]
+    total: number
+    page: number
+    pageSize: number
+    totalPages: number
+    hasNext: boolean
+    hasPrev: boolean
+}
+```

docs/src/content/docs/modules/database/user.md

@@ -0,0 +1,277 @@
+---
+title: "用户管理"
+description: "UserRepository 用户注册、认证、角色管理"
+---
+
+## 概述
+
+`UserRepository` 提供开箱即用的用户管理功能：
+
+- 用户注册与认证
+- 密码哈希（使用 scrypt）
+- 角色管理
+- 账户状态管理
+
+## 快速开始
+
+```typescript
+import { createMongoConnection } from '@esengine/database-drivers'
+import { UserRepository } from '@esengine/database'
+
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+})
+await mongo.connect()
+
+const userRepo = new UserRepository(mongo)
+```
+
+## 用户注册
+
+```typescript
+const user = await userRepo.register({
+    username: 'john',
+    password: 'securePassword123',
+    email: 'john@example.com',      // 可选
+    displayName: 'John Doe',         // 可选
+    roles: ['player']                // 可选，默认 []
+})
+
+console.log(user)
+// {
+//   id: 'uuid-...',
+//   username: 'john',
+//   email: 'john@example.com',
+//   displayName: 'John Doe',
+//   roles: ['player'],
+//   status: 'active',
+//   createdAt: Date,
+//   updatedAt: Date
+// }
+```
+
+**注意**：`register` 返回的 `SafeUser` 不包含密码哈希。
+
+## 用户认证
+
+```typescript
+const user = await userRepo.authenticate('john', 'securePassword123')
+
+if (user) {
+    console.log('登录成功:', user.username)
+} else {
+    console.log('用户名或密码错误')
+}
+```
+
+## 密码管理
+
+### 修改密码
+
+```typescript
+const success = await userRepo.changePassword(
+    userId,
+    'oldPassword123',
+    'newPassword456'
+)
+
+if (success) {
+    console.log('密码修改成功')
+} else {
+    console.log('原密码错误')
+}
+```
+
+### 重置密码
+
+```typescript
+// 管理员直接重置密码
+const success = await userRepo.resetPassword(userId, 'newPassword123')
+```
+
+## 角色管理
+
+### 添加角色
+
+```typescript
+await userRepo.addRole(userId, 'admin')
+await userRepo.addRole(userId, 'moderator')
+```
+
+### 移除角色
+
+```typescript
+await userRepo.removeRole(userId, 'moderator')
+```
+
+### 查询角色
+
+```typescript
+// 查找所有管理员
+const admins = await userRepo.findByRole('admin')
+
+// 检查用户是否有某角色
+const user = await userRepo.findById(userId)
+const isAdmin = user?.roles.includes('admin')
+```
+
+## 查询用户
+
+### 按用户名查找
+
+```typescript
+const user = await userRepo.findByUsername('john')
+```
+
+### 按邮箱查找
+
+```typescript
+const user = await userRepo.findByEmail('john@example.com')
+```
+
+### 按角色查找
+
+```typescript
+const admins = await userRepo.findByRole('admin')
+```
+
+### 使用继承的方法
+
+```typescript
+// 分页查询
+const result = await userRepo.findPaginated(
+    { page: 1, pageSize: 20 },
+    {
+        where: { status: 'active' },
+        sort: { createdAt: 'desc' }
+    }
+)
+
+// 复杂查询
+const users = await userRepo.findMany({
+    where: {
+        status: 'active',
+        roles: { $in: ['admin', 'moderator'] }
+    }
+})
+```
+
+## 账户状态
+
+```typescript
+type UserStatus = 'active' | 'inactive' | 'banned' | 'suspended'
+```
+
+### 更新状态
+
+```typescript
+await userRepo.update(userId, { status: 'banned' })
+```
+
+### 查询特定状态
+
+```typescript
+const activeUsers = await userRepo.findMany({
+    where: { status: 'active' }
+})
+
+const bannedUsers = await userRepo.findMany({
+    where: { status: 'banned' }
+})
+```
+
+## 类型定义
+
+### UserEntity
+
+```typescript
+interface UserEntity extends BaseEntity {
+    username: string
+    passwordHash: string
+    email?: string
+    displayName?: string
+    roles: string[]
+    status: UserStatus
+    lastLoginAt?: Date
+}
+```
+
+### SafeUser
+
+```typescript
+type SafeUser = Omit<UserEntity, 'passwordHash'>
+```
+
+### CreateUserParams
+
+```typescript
+interface CreateUserParams {
+    username: string
+    password: string
+    email?: string
+    displayName?: string
+    roles?: string[]
+}
+```
+
+## 密码工具
+
+独立的密码工具函数：
+
+```typescript
+import { hashPassword, verifyPassword } from '@esengine/database'
+
+// 哈希密码
+const hash = await hashPassword('myPassword123')
+
+// 验证密码
+const isValid = await verifyPassword('myPassword123', hash)
+```
+
+### 安全说明
+
+- 使用 Node.js 内置的 `scrypt` 算法
+- 自动生成随机盐值
+- 默认使用安全的迭代参数
+- 哈希格式：`salt:hash`（均为 hex 编码）
+
+## 扩展 UserRepository
+
+```typescript
+import { UserRepository, UserEntity } from '@esengine/database'
+
+interface GameUser extends UserEntity {
+    level: number
+    experience: number
+    coins: number
+}
+
+class GameUserRepository extends UserRepository {
+    // 重写集合名
+    constructor(connection: IMongoConnection) {
+        super(connection, 'game_users')
+    }
+
+    // 添加游戏相关方法
+    async addExperience(userId: string, amount: number): Promise<GameUser | null> {
+        const user = await this.findById(userId) as GameUser | null
+        if (!user) return null
+
+        const newExp = user.experience + amount
+        const newLevel = Math.floor(newExp / 1000) + 1
+
+        return this.update(userId, {
+            experience: newExp,
+            level: newLevel
+        }) as Promise<GameUser | null>
+    }
+
+    async findTopPlayers(limit: number = 10): Promise<GameUser[]> {
+        return this.findMany({
+            sort: { level: 'desc', experience: 'desc' },
+            limit
+        }) as Promise<GameUser[]>
+    }
+}
+```

docs/src/content/docs/modules/index.md

@@ -37,6 +37,13 @@ ESEngine 提供了丰富的功能模块，可以按需引入到你的项目中
 | [网络同步](/modules/network/) | `@esengine/network` | 多人游戏网络同步 |
 | [事务系统](/modules/transaction/) | `@esengine/transaction` | 游戏事务处理，支持分布式事务 |
 
+### 数据库模块
+
+| 模块 | 包名 | 描述 |
+|------|------|------|
+| [数据库驱动](/modules/database-drivers/) | `@esengine/database-drivers` | MongoDB、Redis 连接管理 |
+| [数据库仓库](/modules/database/) | `@esengine/database` | Repository 模式数据操作 |
+
 ## 安装
 
 所有模块都可以独立安装：

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

@@ -92,6 +92,355 @@ const token = jwtProvider.sign({
 const payload = jwtProvider.decode(token)
 ```
 
+### 自定义提供者
+
+你可以通过实现 `IAuthProvider` 接口来创建自定义认证提供者，以集成任何认证系统（如 OAuth、LDAP、自定义数据库认证等）。
+
+#### IAuthProvider 接口
+
+```typescript
+interface IAuthProvider<TUser = unknown, TCredentials = unknown> {
+    /** 提供者名称 */
+    readonly name: string;
+
+    /** 验证凭证 */
+    verify(credentials: TCredentials): Promise<AuthResult<TUser>>;
+
+    /** 刷新令牌（可选） */
+    refresh?(token: string): Promise<AuthResult<TUser>>;
+
+    /** 撤销令牌（可选） */
+    revoke?(token: string): Promise<boolean>;
+}
+
+interface AuthResult<TUser> {
+    success: boolean;
+    user?: TUser;
+    error?: string;
+    errorCode?: AuthErrorCode;
+    token?: string;
+    expiresAt?: number;
+}
+
+type AuthErrorCode =
+    | 'INVALID_CREDENTIALS'
+    | 'EXPIRED_TOKEN'
+    | 'INVALID_TOKEN'
+    | 'USER_NOT_FOUND'
+    | 'ACCOUNT_DISABLED'
+    | 'RATE_LIMITED'
+    | 'INSUFFICIENT_PERMISSIONS';
+```
+
+#### 自定义提供者示例
+
+**示例 1：数据库密码认证**
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface User {
+    id: string
+    username: string
+    roles: string[]
+}
+
+interface PasswordCredentials {
+    username: string
+    password: string
+}
+
+class DatabaseAuthProvider implements IAuthProvider<User, PasswordCredentials> {
+    readonly name = 'database'
+
+    async verify(credentials: PasswordCredentials): Promise<AuthResult<User>> {
+        const { username, password } = credentials
+
+        // 从数据库查询用户
+        const user = await db.users.findByUsername(username)
+        if (!user) {
+            return {
+                success: false,
+                error: '用户不存在',
+                errorCode: 'USER_NOT_FOUND'
+            }
+        }
+
+        // 验证密码（使用 bcrypt 等库）
+        const isValid = await bcrypt.compare(password, user.passwordHash)
+        if (!isValid) {
+            return {
+                success: false,
+                error: '密码错误',
+                errorCode: 'INVALID_CREDENTIALS'
+            }
+        }
+
+        // 检查账号状态
+        if (user.disabled) {
+            return {
+                success: false,
+                error: '账号已禁用',
+                errorCode: 'ACCOUNT_DISABLED'
+            }
+        }
+
+        return {
+            success: true,
+            user: {
+                id: user.id,
+                username: user.username,
+                roles: user.roles
+            }
+        }
+    }
+}
+```
+
+**示例 2：OAuth/第三方认证**
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface OAuthUser {
+    id: string
+    email: string
+    name: string
+    provider: string
+    roles: string[]
+}
+
+interface OAuthCredentials {
+    provider: 'google' | 'github' | 'discord'
+    accessToken: string
+}
+
+class OAuthProvider implements IAuthProvider<OAuthUser, OAuthCredentials> {
+    readonly name = 'oauth'
+
+    async verify(credentials: OAuthCredentials): Promise<AuthResult<OAuthUser>> {
+        const { provider, accessToken } = credentials
+
+        try {
+            // 根据提供商验证 token
+            const profile = await this.fetchUserProfile(provider, accessToken)
+
+            // 查找或创建本地用户
+            let user = await db.users.findByOAuth(provider, profile.id)
+            if (!user) {
+                user = await db.users.create({
+                    oauthProvider: provider,
+                    oauthId: profile.id,
+                    email: profile.email,
+                    name: profile.name,
+                    roles: ['player']
+                })
+            }
+
+            return {
+                success: true,
+                user: {
+                    id: user.id,
+                    email: user.email,
+                    name: user.name,
+                    provider,
+                    roles: user.roles
+                }
+            }
+        } catch (error) {
+            return {
+                success: false,
+                error: 'OAuth 验证失败',
+                errorCode: 'INVALID_TOKEN'
+            }
+        }
+    }
+
+    private async fetchUserProfile(provider: string, token: string) {
+        switch (provider) {
+            case 'google':
+                return fetch('https://www.googleapis.com/oauth2/v2/userinfo', {
+                    headers: { Authorization: `Bearer ${token}` }
+                }).then(r => r.json())
+            case 'github':
+                return fetch('https://api.github.com/user', {
+                    headers: { Authorization: `Bearer ${token}` }
+                }).then(r => r.json())
+            // 其他提供商...
+            default:
+                throw new Error(`不支持的提供商: ${provider}`)
+        }
+    }
+}
+```
+
+**示例 3：API Key 认证**
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface ApiUser {
+    id: string
+    name: string
+    roles: string[]
+    rateLimit: number
+}
+
+class ApiKeyAuthProvider implements IAuthProvider<ApiUser, string> {
+    readonly name = 'api-key'
+
+    private revokedKeys = new Set<string>()
+
+    async verify(apiKey: string): Promise<AuthResult<ApiUser>> {
+        if (!apiKey || !apiKey.startsWith('sk_')) {
+            return {
+                success: false,
+                error: 'API Key 格式无效',
+                errorCode: 'INVALID_TOKEN'
+            }
+        }
+
+        if (this.revokedKeys.has(apiKey)) {
+            return {
+                success: false,
+                error: 'API Key 已被撤销',
+                errorCode: 'INVALID_TOKEN'
+            }
+        }
+
+        // 从数据库查询 API Key
+        const keyData = await db.apiKeys.findByKey(apiKey)
+        if (!keyData) {
+            return {
+                success: false,
+                error: 'API Key 不存在',
+                errorCode: 'INVALID_CREDENTIALS'
+            }
+        }
+
+        // 检查过期
+        if (keyData.expiresAt && keyData.expiresAt < Date.now()) {
+            return {
+                success: false,
+                error: 'API Key 已过期',
+                errorCode: 'EXPIRED_TOKEN'
+            }
+        }
+
+        return {
+            success: true,
+            user: {
+                id: keyData.userId,
+                name: keyData.name,
+                roles: keyData.roles,
+                rateLimit: keyData.rateLimit
+            },
+            expiresAt: keyData.expiresAt
+        }
+    }
+
+    async revoke(apiKey: string): Promise<boolean> {
+        this.revokedKeys.add(apiKey)
+        await db.apiKeys.revoke(apiKey)
+        return true
+    }
+}
+```
+
+#### 使用自定义提供者
+
+```typescript
+import { createServer } from '@esengine/server'
+import { withAuth } from '@esengine/server/auth'
+
+// 创建自定义提供者
+const dbAuthProvider = new DatabaseAuthProvider()
+
+// 或使用 OAuth 提供者
+const oauthProvider = new OAuthProvider()
+
+// 使用自定义提供者
+const server = withAuth(await createServer({ port: 3000 }), {
+    provider: dbAuthProvider, // 或 oauthProvider
+
+    // 从 WebSocket 连接请求中提取凭证
+    extractCredentials: (req) => {
+        const url = new URL(req.url, 'http://localhost')
+
+        // 对于数据库认证：从查询参数获取
+        const username = url.searchParams.get('username')
+        const password = url.searchParams.get('password')
+        if (username && password) {
+            return { username, password }
+        }
+
+        // 对于 OAuth：从 token 参数获取
+        const provider = url.searchParams.get('provider')
+        const accessToken = url.searchParams.get('access_token')
+        if (provider && accessToken) {
+            return { provider, accessToken }
+        }
+
+        // 对于 API Key：从请求头获取
+        const apiKey = req.headers['x-api-key']
+        if (apiKey) {
+            return apiKey as string
+        }
+
+        return null
+    },
+
+    onAuthFailure: (conn, error) => {
+        console.log(`认证失败: ${error.errorCode} - ${error.error}`)
+    }
+})
+
+await server.start()
+```
+
+#### 组合多个提供者
+
+你可以创建一个复合提供者来支持多种认证方式：
+
+```typescript
+import type { IAuthProvider, AuthResult } from '@esengine/server/auth'
+
+interface MultiAuthCredentials {
+    type: 'jwt' | 'oauth' | 'apikey' | 'password'
+    data: unknown
+}
+
+class MultiAuthProvider implements IAuthProvider<User, MultiAuthCredentials> {
+    readonly name = 'multi'
+
+    constructor(
+        private jwtProvider: JwtAuthProvider<User>,
+        private oauthProvider: OAuthProvider,
+        private apiKeyProvider: ApiKeyAuthProvider,
+        private dbProvider: DatabaseAuthProvider
+    ) {}
+
+    async verify(credentials: MultiAuthCredentials): Promise<AuthResult<User>> {
+        switch (credentials.type) {
+            case 'jwt':
+                return this.jwtProvider.verify(credentials.data as string)
+            case 'oauth':
+                return this.oauthProvider.verify(credentials.data as OAuthCredentials)
+            case 'apikey':
+                return this.apiKeyProvider.verify(credentials.data as string)
+            case 'password':
+                return this.dbProvider.verify(credentials.data as PasswordCredentials)
+            default:
+                return {
+                    success: false,
+                    error: '不支持的认证类型',
+                    errorCode: 'INVALID_CREDENTIALS'
+                }
+        }
+    }
+}
+```
+
 ### Session 提供者
 
 使用服务端会话实现有状态认证：

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

@@ -0,0 +1,441 @@
+---
+title: "分布式房间"
+description: "使用 DistributedRoomManager 实现多服务器房间管理"
+---
+
+## 概述
+
+分布式房间支持允许多个服务器实例共享房间注册表，实现跨服务器玩家路由和故障转移。
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Server A          Server B          Server C          │
+│  ┌─────────┐       ┌─────────┐       ┌─────────┐       │
+│  │ Room 1  │       │ Room 3  │       │ Room 5  │       │
+│  │ Room 2  │       │ Room 4  │       │ Room 6  │       │
+│  └────┬────┘       └────┬────┘       └────┬────┘       │
+│       │                 │                 │             │
+│       └─────────────────┼─────────────────┘             │
+│                         │                               │
+│              ┌──────────▼──────────┐                    │
+│              │  IDistributedAdapter │                   │
+│              │  (Redis / Memory)    │                   │
+│              └─────────────────────┘                    │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 快速开始
+
+### 单机模式（测试用）
+
+```typescript
+import {
+    DistributedRoomManager,
+    MemoryAdapter,
+    Room
+} from '@esengine/server';
+
+// 定义房间类型
+class GameRoom extends Room {
+    maxPlayers = 4;
+}
+
+// 创建适配器和管理器
+const adapter = new MemoryAdapter();
+const manager = new DistributedRoomManager(adapter, {
+    serverId: 'server-1',
+    serverAddress: 'localhost',
+    serverPort: 3000
+}, (conn, type, data) => conn.send(JSON.stringify({ type, data })));
+
+// 注册房间类型
+manager.define('game', GameRoom);
+
+// 启动管理器
+await manager.start();
+
+// 分布式加入/创建房间
+const result = await manager.joinOrCreateDistributed('game', 'player-1', conn);
+if ('redirect' in result) {
+    // 玩家应连接到其他服务器
+    console.log(`重定向到: ${result.redirect}`);
+} else {
+    // 玩家加入本地房间
+    const { room, player } = result;
+}
+
+// 优雅关闭
+await manager.stop(true);
+```
+
+### 多服务器模式（生产用）
+
+```typescript
+import Redis from 'ioredis';
+import { DistributedRoomManager, RedisAdapter } from '@esengine/server';
+
+const adapter = new RedisAdapter({
+    factory: () => new Redis({
+        host: 'redis.example.com',
+        port: 6379
+    }),
+    prefix: 'game:',
+    serverTtl: 30,
+    snapshotTtl: 86400
+});
+
+const manager = new DistributedRoomManager(adapter, {
+    serverId: process.env.SERVER_ID,
+    serverAddress: process.env.PUBLIC_IP,
+    serverPort: 3000,
+    heartbeatInterval: 5000,
+    snapshotInterval: 30000,
+    enableFailover: true,
+    capacity: 100
+}, sendFn);
+```
+
+## DistributedRoomManager
+
+### 配置选项
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `serverId` | `string` | 必填 | 服务器唯一标识 |
+| `serverAddress` | `string` | 必填 | 客户端连接的公开地址 |
+| `serverPort` | `number` | 必填 | 服务器端口 |
+| `heartbeatInterval` | `number` | `5000` | 心跳间隔（毫秒） |
+| `snapshotInterval` | `number` | `30000` | 状态快照间隔，0 禁用 |
+| `migrationTimeout` | `number` | `10000` | 房间迁移超时 |
+| `enableFailover` | `boolean` | `true` | 启用自动故障转移 |
+| `capacity` | `number` | `100` | 本服务器最大房间数 |
+
+### 生命周期方法
+
+#### start()
+
+启动分布式房间管理器。连接适配器、注册服务器、启动心跳。
+
+```typescript
+await manager.start();
+```
+
+#### stop(graceful?)
+
+停止管理器。如果 `graceful=true`，将服务器标记为 draining 并保存所有房间快照。
+
+```typescript
+await manager.stop(true);
+```
+
+### 路由方法
+
+#### joinOrCreateDistributed()
+
+分布式感知的加入或创建房间。返回本地房间的 `{ room, player }` 或远程房间的 `{ redirect: string }`。
+
+```typescript
+const result = await manager.joinOrCreateDistributed('game', 'player-1', conn);
+
+if ('redirect' in result) {
+    // 客户端应重定向到其他服务器
+    res.json({ redirect: result.redirect });
+} else {
+    // 玩家加入了本地房间
+    const { room, player } = result;
+}
+```
+
+#### route()
+
+将玩家路由到合适的房间/服务器。
+
+```typescript
+const result = await manager.route({
+    roomType: 'game',
+    playerId: 'p1'
+});
+
+switch (result.type) {
+    case 'local':      // 房间在本服务器
+        break;
+    case 'redirect':   // 房间在其他服务器
+        // result.serverAddress 包含目标服务器地址
+        break;
+    case 'create':     // 没有可用房间，需要创建
+        break;
+    case 'unavailable': // 无法找到或创建房间
+        // result.reason 包含错误信息
+        break;
+}
+```
+
+### 状态管理
+
+#### saveSnapshot()
+
+手动保存房间状态快照。
+
+```typescript
+await manager.saveSnapshot(roomId);
+```
+
+#### restoreFromSnapshot()
+
+从保存的快照恢复房间。
+
+```typescript
+const success = await manager.restoreFromSnapshot(roomId);
+```
+
+### 查询方法
+
+#### getServers()
+
+获取所有在线服务器。
+
+```typescript
+const servers = await manager.getServers();
+```
+
+#### queryDistributedRooms()
+
+查询所有服务器上的房间。
+
+```typescript
+const rooms = await manager.queryDistributedRooms({
+    roomType: 'game',
+    hasSpace: true,
+    notLocked: true
+});
+```
+
+## IDistributedAdapter
+
+分布式后端的接口。实现此接口以支持 Redis、消息队列等。
+
+### 内置适配器
+
+#### MemoryAdapter
+
+用于测试和单机模式的内存实现。
+
+```typescript
+const adapter = new MemoryAdapter({
+    serverTtl: 15000,      // 无心跳后服务器离线时间（毫秒）
+    enableTtlCheck: true,  // 启用自动 TTL 检查
+    ttlCheckInterval: 5000 // TTL 检查间隔（毫秒）
+});
+```
+
+#### RedisAdapter
+
+用于生产环境多服务器部署的 Redis 实现。
+
+```typescript
+import Redis from 'ioredis';
+import { RedisAdapter } from '@esengine/server';
+
+const adapter = new RedisAdapter({
+    factory: () => new Redis('redis://localhost:6379'),
+    prefix: 'game:',       // 键前缀（默认: 'dist:'）
+    serverTtl: 30,         // 服务器 TTL（秒，默认: 30）
+    roomTtl: 0,            // 房间 TTL，0 = 永不过期（默认: 0）
+    snapshotTtl: 86400,    // 快照 TTL（秒，默认: 24 小时）
+    channel: 'game:events' // Pub/Sub 频道（默认: 'distributed:events'）
+});
+```
+
+**RedisAdapter 配置：**
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `factory` | `() => RedisClient` | 必填 | Redis 客户端工厂（惰性连接） |
+| `prefix` | `string` | `'dist:'` | 所有 Redis 键的前缀 |
+| `serverTtl` | `number` | `30` | 服务器 TTL（秒） |
+| `roomTtl` | `number` | `0` | 房间 TTL（秒），0 = 不过期 |
+| `snapshotTtl` | `number` | `86400` | 快照 TTL（秒） |
+| `channel` | `string` | `'distributed:events'` | Pub/Sub 频道名 |
+
+**功能特性：**
+- 带自动心跳 TTL 的服务器注册
+- 跨服务器查找的房间注册
+- 可配置 TTL 的状态快照
+- 跨服务器事件的 Pub/Sub
+- 使用 Redis SET NX 的分布式锁
+
+### 自定义适配器
+
+```typescript
+import type { IDistributedAdapter } from '@esengine/server';
+
+class MyAdapter implements IDistributedAdapter {
+    // 生命周期
+    async connect(): Promise<void> { }
+    async disconnect(): Promise<void> { }
+    isConnected(): boolean { return true; }
+
+    // 服务器注册
+    async registerServer(server: ServerRegistration): Promise<void> { }
+    async unregisterServer(serverId: string): Promise<void> { }
+    async heartbeat(serverId: string): Promise<void> { }
+    async getServers(): Promise<ServerRegistration[]> { return []; }
+
+    // 房间注册
+    async registerRoom(room: RoomRegistration): Promise<void> { }
+    async unregisterRoom(roomId: string): Promise<void> { }
+    async queryRooms(query: RoomQuery): Promise<RoomRegistration[]> { return []; }
+    async findAvailableRoom(roomType: string): Promise<RoomRegistration | null> { return null; }
+
+    // 状态快照
+    async saveSnapshot(snapshot: RoomSnapshot): Promise<void> { }
+    async loadSnapshot(roomId: string): Promise<RoomSnapshot | null> { return null; }
+
+    // 发布/订阅
+    async publish(event: DistributedEvent): Promise<void> { }
+    async subscribe(pattern: string, handler: Function): Promise<() => void> { return () => {}; }
+
+    // 分布式锁
+    async acquireLock(key: string, ttlMs: number): Promise<boolean> { return true; }
+    async releaseLock(key: string): Promise<void> { }
+}
+```
+
+## 玩家路由流程
+
+```
+客户端                    服务器 A                    服务器 B
+  │                          │                           │
+  │─── joinOrCreate ────────►│                           │
+  │                          │                           │
+  │                          │── findAvailableRoom() ───►│
+  │                          │◄──── 服务器 B 上有房间 ────│
+  │                          │                           │
+  │◄─── redirect: B:3001 ────│                           │
+  │                          │                           │
+  │───────────────── 连接到服务器 B ────────────────────►│
+  │                          │                           │
+  │◄─────────────────────────────── 已加入 ─────────────│
+```
+
+## 事件类型
+
+分布式系统发布以下事件：
+
+| 事件 | 描述 |
+|------|------|
+| `server:online` | 服务器上线 |
+| `server:offline` | 服务器离线 |
+| `server:draining` | 服务器正在排空 |
+| `room:created` | 房间已创建 |
+| `room:disposed` | 房间已销毁 |
+| `room:updated` | 房间信息已更新 |
+| `room:message` | 跨服务器房间消息 |
+| `room:migrated` | 房间已迁移到其他服务器 |
+| `player:joined` | 玩家加入房间 |
+| `player:left` | 玩家离开房间 |
+
+## 最佳实践
+
+1. **使用唯一服务器 ID** - 使用主机名、容器 ID 或 UUID
+
+2. **配置合适的心跳** - 在新鲜度和网络开销之间平衡
+
+3. **为有状态房间启用快照** - 确保房间状态在服务器重启后存活
+
+4. **优雅处理重定向** - 客户端应重新连接到目标服务器
+   ```typescript
+   // 客户端处理重定向
+   if (response.redirect) {
+       await client.disconnect();
+       await client.connect(response.redirect);
+       await client.joinRoom(roomId);
+   }
+   ```
+
+5. **使用分布式锁** - 防止 joinOrCreate 中的竞态条件
+
+## 使用 createServer 集成
+
+最简单的使用方式是通过 `createServer` 的 `distributed` 配置：
+
+```typescript
+import { createServer } from '@esengine/server';
+import { RedisAdapter, Room } from '@esengine/server';
+import Redis from 'ioredis';
+
+class GameRoom extends Room {
+    maxPlayers = 4;
+}
+
+const server = await createServer({
+    port: 3000,
+    distributed: {
+        enabled: true,
+        adapter: new RedisAdapter({ factory: () => new Redis() }),
+        serverId: 'server-1',
+        serverAddress: 'ws://192.168.1.100',
+        serverPort: 3000,
+        enableFailover: true,
+        capacity: 100
+    }
+});
+
+server.define('game', GameRoom);
+await server.start();
+```
+
+当客户端调用 `JoinRoom` API 时，服务器会自动：
+1. 查找可用房间（本地或远程）
+2. 如果房间在其他服务器，发送 `$redirect` 消息给客户端
+3. 客户端收到重定向消息后连接到目标服务器
+
+## 负载均衡
+
+使用 `LoadBalancedRouter` 进行服务器选择：
+
+```typescript
+import { LoadBalancedRouter, createLoadBalancedRouter } from '@esengine/server';
+
+// 使用工厂函数
+const router = createLoadBalancedRouter('least-players');
+
+// 或直接创建
+const router = new LoadBalancedRouter({
+    strategy: 'least-rooms',  // 选择房间数最少的服务器
+    preferLocal: true         // 优先选择本地服务器
+});
+
+// 可用策略
+// - 'round-robin': 轮询
+// - 'least-rooms': 最少房间数
+// - 'least-players': 最少玩家数
+// - 'random': 随机选择
+// - 'weighted': 权重（基于容量使用率）
+```
+
+## 故障转移
+
+当服务器离线时，启用 `enableFailover` 后系统会自动：
+
+1. 检测到服务器离线（通过心跳超时）
+2. 查询该服务器上的所有房间
+3. 使用分布式锁防止多服务器同时恢复
+4. 从快照恢复房间状态
+5. 发布 `room:migrated` 事件通知其他服务器
+
+```typescript
+// 确保定期保存快照
+const manager = new DistributedRoomManager(adapter, {
+    serverId: 'server-1',
+    serverAddress: 'localhost',
+    serverPort: 3000,
+    snapshotInterval: 30000,  // 每 30 秒保存快照
+    enableFailover: true      // 启用故障转移
+}, sendFn);
+```
+
+## 后续版本
+
+- Redis Cluster 支持
+- 更多负载均衡策略（地理位置、延迟感知）

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

@@ -0,0 +1,679 @@
+---
+title: "HTTP 路由"
+description: "HTTP REST API 路由功能，支持与 WebSocket 共用端口"
+---
+
+`@esengine/server` 内置了轻量级的 HTTP 路由功能，可以与 WebSocket 服务共用同一端口，方便实现 REST API。
+
+## 快速开始
+
+### 内联路由定义
+
+最简单的方式是在创建服务器时直接定义 HTTP 路由：
+
+```typescript
+import { createServer } from '@esengine/server'
+
+const server = await createServer({
+    port: 3000,
+    http: {
+        '/api/health': (req, res) => {
+            res.json({ status: 'ok', time: Date.now() })
+        },
+        '/api/users': {
+            GET: (req, res) => {
+                res.json({ users: [] })
+            },
+            POST: async (req, res) => {
+                const body = req.body as { name: string }
+                res.status(201).json({ id: '1', name: body.name })
+            }
+        }
+    },
+    cors: true  // 启用 CORS
+})
+
+await server.start()
+```
+
+### 文件路由
+
+对于较大的项目，推荐使用文件路由。创建 `src/http` 目录，每个文件对应一个路由：
+
+```typescript
+// src/http/login.ts
+import { defineHttp } from '@esengine/server'
+
+interface LoginBody {
+    username: string
+    password: string
+}
+
+export default defineHttp<LoginBody>({
+    method: 'POST',
+    handler(req, res) {
+        const { username, password } = req.body as LoginBody
+
+        // 验证用户...
+        if (username === 'admin' && password === '123456') {
+            res.json({ token: 'jwt-token-here', userId: 'user-1' })
+        } else {
+            res.error(401, '用户名或密码错误')
+        }
+    }
+})
+```
+
+```typescript
+// server.ts
+import { createServer } from '@esengine/server'
+
+const server = await createServer({
+    port: 3000,
+    httpDir: './src/http',   // HTTP 路由目录
+    httpPrefix: '/api',       // 路由前缀
+    cors: true
+})
+
+await server.start()
+// 路由: POST /api/login
+```
+
+## defineHttp 定义
+
+`defineHttp` 用于定义类型安全的 HTTP 处理器：
+
+```typescript
+import { defineHttp } from '@esengine/server'
+
+interface CreateUserBody {
+    username: string
+    email: string
+    password: string
+}
+
+export default defineHttp<CreateUserBody>({
+    // HTTP 方法（默认 POST）
+    method: 'POST',
+
+    // 处理函数
+    handler(req, res) {
+        const body = req.body as CreateUserBody
+        // 处理请求...
+        res.status(201).json({ id: 'new-user-id' })
+    }
+})
+```
+
+### 支持的 HTTP 方法
+
+```typescript
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS'
+```
+
+## HttpRequest 对象
+
+HTTP 请求对象包含以下属性：
+
+```typescript
+interface HttpRequest {
+    /** 原始 Node.js IncomingMessage */
+    raw: IncomingMessage
+
+    /** HTTP 方法 */
+    method: string
+
+    /** 请求路径 */
+    path: string
+
+    /** 路由参数（从 URL 路径提取，如 /users/:id） */
+    params: Record<string, string>
+
+    /** 查询参数 */
+    query: Record<string, string>
+
+    /** 请求头 */
+    headers: Record<string, string | string[] | undefined>
+
+    /** 解析后的请求体 */
+    body: unknown
+
+    /** 客户端 IP */
+    ip: string
+}
+```
+
+### 使用示例
+
+```typescript
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // 获取查询参数
+        const page = parseInt(req.query.page ?? '1')
+        const limit = parseInt(req.query.limit ?? '10')
+
+        // 获取请求头
+        const authHeader = req.headers.authorization
+
+        // 获取客户端 IP
+        console.log('Request from:', req.ip)
+
+        res.json({ page, limit })
+    }
+})
+```
+
+### 请求体解析
+
+请求体会根据 `Content-Type` 自动解析：
+
+- `application/json` - 解析为 JSON 对象
+- `application/x-www-form-urlencoded` - 解析为键值对对象
+- 其他 - 保持原始字符串
+
+```typescript
+export default defineHttp<{ name: string; age: number }>({
+    method: 'POST',
+    handler(req, res) {
+        // body 已自动解析
+        const { name, age } = req.body as { name: string; age: number }
+        res.json({ received: { name, age } })
+    }
+})
+```
+
+## HttpResponse 对象
+
+HTTP 响应对象提供链式 API：
+
+```typescript
+interface HttpResponse {
+    /** 原始 Node.js ServerResponse */
+    raw: ServerResponse
+
+    /** 设置状态码 */
+    status(code: number): HttpResponse
+
+    /** 设置响应头 */
+    header(name: string, value: string): HttpResponse
+
+    /** 发送 JSON 响应 */
+    json(data: unknown): void
+
+    /** 发送文本响应 */
+    text(data: string): void
+
+    /** 发送错误响应 */
+    error(code: number, message: string): void
+}
+```
+
+### 使用示例
+
+```typescript
+export default defineHttp({
+    method: 'POST',
+    handler(req, res) {
+        // 设置状态码和自定义头
+        res
+            .status(201)
+            .header('X-Custom-Header', 'value')
+            .json({ created: true })
+    }
+})
+```
+
+```typescript
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // 发送错误响应
+        res.error(404, '资源不存在')
+        // 等价于: res.status(404).json({ error: '资源不存在' })
+    }
+})
+```
+
+```typescript
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // 发送纯文本
+        res.text('Hello, World!')
+    }
+})
+```
+
+## 文件路由规范
+
+### 命名转换
+
+文件名会自动转换为路由路径：
+
+| 文件路径 | 路由路径（prefix=/api） |
+|---------|----------------------|
+| `login.ts` | `/api/login` |
+| `users/profile.ts` | `/api/users/profile` |
+| `users/[id].ts` | `/api/users/:id` |
+| `game/room/[roomId].ts` | `/api/game/room/:roomId` |
+
+### 动态路由参数
+
+使用 `[param]` 语法定义动态参数：
+
+```typescript
+// src/http/users/[id].ts
+import { defineHttp } from '@esengine/server'
+
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        // 直接从 params 获取路由参数
+        const { id } = req.params
+        res.json({ userId: id })
+    }
+})
+```
+
+多个参数的情况：
+
+```typescript
+// src/http/users/[userId]/posts/[postId].ts
+import { defineHttp } from '@esengine/server'
+
+export default defineHttp({
+    method: 'GET',
+    handler(req, res) {
+        const { userId, postId } = req.params
+        res.json({ userId, postId })
+    }
+})
+```
+
+### 跳过规则
+
+以下文件会被自动跳过：
+
+- 以 `_` 开头的文件（如 `_helper.ts`）
+- `index.ts` / `index.js` 文件
+- 非 `.ts` / `.js` / `.mts` / `.mjs` 文件
+
+### 目录结构示例
+
+```
+src/
+└── http/
+    ├── _utils.ts        # 跳过（下划线开头）
+    ├── index.ts         # 跳过（index 文件）
+    ├── health.ts        # GET /api/health
+    ├── login.ts         # POST /api/login
+    ├── register.ts      # POST /api/register
+    └── users/
+        ├── index.ts     # 跳过
+        ├── list.ts      # GET /api/users/list
+        └── [id].ts      # GET /api/users/:id
+```
+
+## CORS 配置
+
+### 快速启用
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    cors: true  // 使用默认配置
+})
+```
+
+### 自定义配置
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    cors: {
+        // 允许的来源
+        origin: ['http://localhost:5173', 'https://myapp.com'],
+        // 或使用通配符
+        // origin: '*',
+        // origin: true,  // 反射请求来源
+
+        // 允许的 HTTP 方法
+        methods: ['GET', 'POST', 'PUT', 'DELETE'],
+
+        // 允许的请求头
+        allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
+
+        // 是否允许携带凭证（cookies）
+        credentials: true,
+
+        // 预检请求缓存时间（秒）
+        maxAge: 86400
+    }
+})
+```
+
+### CorsOptions 类型
+
+```typescript
+interface CorsOptions {
+    /** 允许的来源：字符串、字符串数组、true（反射）或 '*' */
+    origin?: string | string[] | boolean
+
+    /** 允许的 HTTP 方法 */
+    methods?: string[]
+
+    /** 允许的请求头 */
+    allowedHeaders?: string[]
+
+    /** 是否允许携带凭证 */
+    credentials?: boolean
+
+    /** 预检请求缓存时间（秒） */
+    maxAge?: number
+}
+```
+
+## 路由合并
+
+文件路由和内联路由可以同时使用，内联路由优先级更高：
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    httpDir: './src/http',
+    httpPrefix: '/api',
+
+    // 内联路由会与文件路由合并
+    http: {
+        '/health': (req, res) => res.json({ status: 'ok' }),
+        '/api/special': (req, res) => res.json({ special: true })
+    }
+})
+```
+
+## 与 WebSocket 共用端口
+
+HTTP 路由与 WebSocket 服务自动共用同一端口：
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    // WebSocket 相关配置
+    apiDir: './src/api',
+    msgDir: './src/msg',
+
+    // HTTP 相关配置
+    httpDir: './src/http',
+    httpPrefix: '/api',
+    cors: true
+})
+
+await server.start()
+
+// 同一端口 3000：
+// - WebSocket: ws://localhost:3000
+// - HTTP API:  http://localhost:3000/api/*
+```
+
+## 完整示例
+
+### 游戏服务器登录 API
+
+```typescript
+// src/http/auth/login.ts
+import { defineHttp } from '@esengine/server'
+import { createJwtAuthProvider } from '@esengine/server/auth'
+
+interface LoginRequest {
+    username: string
+    password: string
+}
+
+interface LoginResponse {
+    token: string
+    userId: string
+    expiresAt: number
+}
+
+const jwtProvider = createJwtAuthProvider({
+    secret: process.env.JWT_SECRET!,
+    expiresIn: 3600
+})
+
+export default defineHttp<LoginRequest>({
+    method: 'POST',
+    async handler(req, res) {
+        const { username, password } = req.body as LoginRequest
+
+        // 验证用户
+        const user = await db.users.findByUsername(username)
+        if (!user || !await verifyPassword(password, user.passwordHash)) {
+            res.error(401, '用户名或密码错误')
+            return
+        }
+
+        // 生成 JWT
+        const token = jwtProvider.sign({
+            sub: user.id,
+            name: user.username,
+            roles: user.roles
+        })
+
+        const response: LoginResponse = {
+            token,
+            userId: user.id,
+            expiresAt: Date.now() + 3600 * 1000
+        }
+
+        res.json(response)
+    }
+})
+```
+
+### 游戏数据查询 API
+
+```typescript
+// src/http/game/leaderboard.ts
+import { defineHttp } from '@esengine/server'
+
+export default defineHttp({
+    method: 'GET',
+    async handler(req, res) {
+        const limit = parseInt(req.query.limit ?? '10')
+        const offset = parseInt(req.query.offset ?? '0')
+
+        const players = await db.players.findMany({
+            sort: { score: 'desc' },
+            limit,
+            offset
+        })
+
+        res.json({
+            data: players,
+            pagination: { limit, offset }
+        })
+    }
+})
+```
+
+## 中间件
+
+### 中间件类型
+
+中间件是在路由处理前后执行的函数：
+
+```typescript
+type HttpMiddleware = (
+    req: HttpRequest,
+    res: HttpResponse,
+    next: () => Promise<void>
+) => void | Promise<void>
+```
+
+### 内置中间件
+
+```typescript
+import {
+    requestLogger,
+    bodyLimit,
+    responseTime,
+    requestId,
+    securityHeaders
+} from '@esengine/server'
+
+const server = await createServer({
+    port: 3000,
+    http: { /* ... */ },
+    // 全局中间件通过 createHttpRouter 配置
+})
+```
+
+#### requestLogger - 请求日志
+
+```typescript
+import { requestLogger } from '@esengine/server'
+
+// 记录请求和响应时间
+requestLogger()
+
+// 同时记录请求体
+requestLogger({ logBody: true })
+```
+
+#### bodyLimit - 请求体大小限制
+
+```typescript
+import { bodyLimit } from '@esengine/server'
+
+// 限制请求体为 1MB
+bodyLimit(1024 * 1024)
+```
+
+#### responseTime - 响应时间头
+
+```typescript
+import { responseTime } from '@esengine/server'
+
+// 自动添加 X-Response-Time 响应头
+responseTime()
+```
+
+#### requestId - 请求 ID
+
+```typescript
+import { requestId } from '@esengine/server'
+
+// 自动生成并添加 X-Request-ID 响应头
+requestId()
+
+// 自定义头名称
+requestId('X-Trace-ID')
+```
+
+#### securityHeaders - 安全头
+
+```typescript
+import { securityHeaders } from '@esengine/server'
+
+// 添加常用安全响应头
+securityHeaders()
+
+// 自定义配置
+securityHeaders({
+    hidePoweredBy: true,
+    frameOptions: 'DENY',
+    noSniff: true
+})
+```
+
+### 自定义中间件
+
+```typescript
+import type { HttpMiddleware } from '@esengine/server'
+
+// 认证中间件
+const authMiddleware: HttpMiddleware = async (req, res, next) => {
+    const token = req.headers.authorization?.replace('Bearer ', '')
+
+    if (!token) {
+        res.error(401, 'Unauthorized')
+        return  // 不调用 next()，终止请求
+    }
+
+    // 验证 token...
+    (req as any).userId = 'decoded-user-id'
+
+    await next()  // 继续执行后续中间件和处理器
+}
+```
+
+### 使用中间件
+
+#### 使用 createHttpRouter
+
+```typescript
+import { createHttpRouter, requestLogger, bodyLimit } from '@esengine/server'
+
+const router = createHttpRouter({
+    '/api/users': (req, res) => res.json([]),
+    '/api/admin': {
+        GET: {
+            handler: (req, res) => res.json({ admin: true }),
+            middlewares: [adminAuthMiddleware]  // 路由级中间件
+        }
+    }
+}, {
+    middlewares: [requestLogger(), bodyLimit(1024 * 1024)],  // 全局中间件
+    timeout: 30000  // 全局超时 30 秒
+})
+```
+
+## 请求超时
+
+### 全局超时
+
+```typescript
+import { createHttpRouter } from '@esengine/server'
+
+const router = createHttpRouter({
+    '/api/data': async (req, res) => {
+        // 如果处理超过 30 秒，自动返回 408 Request Timeout
+        await someSlowOperation()
+        res.json({ data: 'result' })
+    }
+}, {
+    timeout: 30000  // 30 秒
+})
+```
+
+### 路由级超时
+
+```typescript
+const router = createHttpRouter({
+    '/api/quick': (req, res) => res.json({ fast: true }),
+
+    '/api/slow': {
+        POST: {
+            handler: async (req, res) => {
+                await verySlowOperation()
+                res.json({ done: true })
+            },
+            timeout: 120000  // 这个路由允许 2 分钟
+        }
+    }
+}, {
+    timeout: 10000  // 全局 10 秒（被路由级覆盖）
+})
+```
+
+## 最佳实践
+
+1. **使用 defineHttp** - 获得更好的类型提示和代码组织
+2. **统一错误处理** - 使用 `res.error()` 返回一致的错误格式
+3. **启用 CORS** - 前后端分离时必须配置
+4. **目录组织** - 按功能模块组织 HTTP 路由文件
+5. **验证输入** - 始终验证 `req.body` 和 `req.query` 的内容
+6. **状态码规范** - 遵循 HTTP 状态码规范（200、201、400、401、404、500 等）
+7. **使用中间件** - 通过中间件实现认证、日志、限流等横切关注点
+8. **设置超时** - 避免慢请求阻塞服务器

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

@@ -147,6 +147,7 @@ service.on('chat', (data) => {
 
 - [客户端使用](/modules/network/client/) - NetworkPlugin、组件和系统
 - [服务器端](/modules/network/server/) - GameServer 和 Room 管理
+- [分布式房间](/modules/network/distributed/) - 多服务器房间管理和玩家路由
 - [状态同步](/modules/network/sync/) - 插值和快照缓冲
 - [客户端预测](/modules/network/prediction/) - 输入预测和服务器校正
 - [兴趣区域 (AOI)](/modules/network/aoi/) - 视野过滤和带宽优化

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

@@ -79,10 +79,47 @@ await server.start()
 | `tickRate` | `number` | `20` | 全局 Tick 频率 (Hz) |
 | `apiDir` | `string` | `'src/api'` | API 处理器目录 |
 | `msgDir` | `string` | `'src/msg'` | 消息处理器目录 |
+| `httpDir` | `string` | `'src/http'` | HTTP 路由目录 |
+| `httpPrefix` | `string` | `'/api'` | HTTP 路由前缀 |
+| `cors` | `boolean \| CorsOptions` | - | CORS 配置 |
 | `onStart` | `(port) => void` | - | 启动回调 |
 | `onConnect` | `(conn) => void` | - | 连接回调 |
 | `onDisconnect` | `(conn) => void` | - | 断开回调 |
 
+## HTTP 路由
+
+支持 HTTP API 与 WebSocket 共用端口，适用于登录、注册等场景。
+
+```typescript
+const server = await createServer({
+    port: 3000,
+    httpDir: './src/http',   // HTTP 路由目录
+    httpPrefix: '/api',       // 路由前缀
+    cors: true,
+
+    // 或内联定义
+    http: {
+        '/health': (req, res) => res.json({ status: 'ok' })
+    }
+})
+```
+
+```typescript
+// src/http/login.ts
+import { defineHttp } from '@esengine/server'
+
+export default defineHttp<{ username: string; password: string }>({
+    method: 'POST',
+    handler(req, res) {
+        const { username, password } = req.body
+        // 验证并返回 token...
+        res.json({ token: '...' })
+    }
+})
+```
+
+> 详细文档请参考 [HTTP 路由](/modules/network/http)
+
 ## Room 系统
 
 Room 是游戏房间的基类，管理玩家和游戏状态。
@@ -243,6 +280,122 @@ class GameRoom extends Room {
 }
 ```
 
+## Schema 验证
+
+使用内置的 Schema 验证系统进行运行时类型验证：
+
+### 基础用法
+
+```typescript
+import { s, defineApiWithSchema } from '@esengine/server'
+
+// 定义 Schema
+const MoveSchema = s.object({
+    x: s.number(),
+    y: s.number(),
+    speed: s.number().optional()
+})
+
+// 类型自动推断
+type Move = s.infer<typeof MoveSchema>  // { x: number; y: number; speed?: number }
+
+// 使用 Schema 定义 API（自动验证）
+export default defineApiWithSchema(MoveSchema, {
+    handler(req, ctx) {
+        // req 已验证，类型安全
+        console.log(req.x, req.y)
+    }
+})
+```
+
+### 验证器类型
+
+| 类型 | 示例 | 描述 |
+|------|------|------|
+| `s.string()` | `s.string().min(1).max(50)` | 字符串，支持长度限制 |
+| `s.number()` | `s.number().min(0).int()` | 数字，支持范围和整数限制 |
+| `s.boolean()` | `s.boolean()` | 布尔值 |
+| `s.literal()` | `s.literal('admin')` | 字面量类型 |
+| `s.object()` | `s.object({ name: s.string() })` | 对象 |
+| `s.array()` | `s.array(s.number())` | 数组 |
+| `s.enum()` | `s.enum(['a', 'b'] as const)` | 枚举 |
+| `s.union()` | `s.union([s.string(), s.number()])` | 联合类型 |
+| `s.record()` | `s.record(s.any())` | 记录类型 |
+
+### 修饰符
+
+```typescript
+// 可选字段
+s.string().optional()
+
+// 默认值
+s.number().default(0)
+
+// 可为 null
+s.string().nullable()
+
+// 字符串验证
+s.string().min(1).max(100).email().url().regex(/^[a-z]+$/)
+
+// 数字验证
+s.number().min(0).max(100).int().positive()
+
+// 数组验证
+s.array(s.string()).min(1).max(10).nonempty()
+
+// 对象验证
+s.object({ ... }).strict()  // 不允许额外字段
+s.object({ ... }).partial() // 所有字段可选
+s.object({ ... }).pick('name', 'age')  // 选择字段
+s.object({ ... }).omit('password')     // 排除字段
+```
+
+### 消息验证
+
+```typescript
+import { s, defineMsgWithSchema } from '@esengine/server'
+
+const InputSchema = s.object({
+    keys: s.array(s.string()),
+    timestamp: s.number()
+})
+
+export default defineMsgWithSchema(InputSchema, {
+    handler(msg, ctx) {
+        // msg 已验证
+        console.log(msg.keys, msg.timestamp)
+    }
+})
+```
+
+### 手动验证
+
+```typescript
+import { s, parse, safeParse, createGuard } from '@esengine/server'
+
+const UserSchema = s.object({
+    name: s.string(),
+    age: s.number().int().min(0)
+})
+
+// 抛出错误
+const user = parse(UserSchema, data)
+
+// 返回结果对象
+const result = safeParse(UserSchema, data)
+if (result.success) {
+    console.log(result.data)
+} else {
+    console.error(result.error)
+}
+
+// 类型守卫
+const isUser = createGuard(UserSchema)
+if (isUser(data)) {
+    // data 是 User 类型
+}
+```
+
 ## 协议定义
 
 在 `src/shared/protocol.ts` 中定义客户端和服务端共享的类型：

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 组件状态同步。

docs/src/content/docs/modules/transaction/storage.md

@@ -125,23 +125,24 @@ tx:data:{key}           - 业务数据
 
 ## MongoStorage
 
-MongoDB 存储，适用于需要持久化和复杂查询的场景。使用工厂模式实现惰性连接。
+MongoDB 存储，适用于需要持久化和复杂查询的场景。使用 `@esengine/database-drivers` 的共享连接。
 
 ```typescript
-import { MongoClient } from 'mongodb';
-import { MongoStorage } from '@esengine/transaction';
+import { createMongoConnection } from '@esengine/database-drivers';
+import { createMongoStorage, TransactionManager } from '@esengine/transaction';
 
-// 工厂模式：惰性连接，首次操作时才创建连接
-const storage = new MongoStorage({
-    factory: async () => {
-        const client = new MongoClient('mongodb://localhost:27017');
-        await client.connect();
-        return client;
-    },
-    database: 'game',
-    transactionCollection: 'transactions',  // 事务日志集合
-    dataCollection: 'transaction_data',     // 业务数据集合
-    lockCollection: 'transaction_locks',    // 锁集合
+// 创建共享连接
+const mongo = createMongoConnection({
+    uri: 'mongodb://localhost:27017',
+    database: 'game'
+});
+await mongo.connect();
+
+// 使用共享连接创建存储
+const storage = createMongoStorage(mongo, {
+    transactionCollection: 'transactions',  // 事务日志集合（可选）
+    dataCollection: 'transaction_data',     // 业务数据集合（可选）
+    lockCollection: 'transaction_locks',    // 锁集合（可选）
 });
 
 // 创建索引（首次运行时执行）
@@ -149,11 +150,14 @@ await storage.ensureIndexes();
 
 const manager = new TransactionManager({ storage });
 
-// 使用后关闭连接
+// 关闭存储（不会关闭共享连接）
 await storage.close();
 
-// 或使用 await using 自动关闭 (TypeScript 5.2+)
-await using storage = new MongoStorage({ ... });
+// 共享连接可继续用于其他模块
+const userRepo = new UserRepository(mongo);  // @esengine/database
+
+// 最后关闭共享连接
+await mongo.disconnect();
 ```
 
 ### 特点

package.json

@@ -13,6 +13,7 @@
     "packages/network-ext/*",
     "packages/editor/*",
     "packages/editor/plugins/*",
+    "packages/devtools/*",
     "packages/rust/*",
     "packages/tools/*"
   ],
@@ -74,6 +75,7 @@
     "lint:fix": "turbo run lint:fix",
     "build:wasm": "cd packages/rust/engine && wasm-pack build --dev --out-dir pkg",
     "build:wasm:release": "cd packages/rust/engine && wasm-pack build --release --out-dir pkg",
+    "build:rapier2d": "node scripts/build-rapier2d.mjs",
     "copy-modules": "node scripts/copy-engine-modules.mjs"
   },
   "author": "yhh",

packages/devtools/node-editor/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @esengine/node-editor
+
+## 1.2.2
+
+### Patch Changes
+
+- [#435](https://github.com/esengine/esengine/pull/435) [`c2acd14`](https://github.com/esengine/esengine/commit/c2acd14fce83af6cd116b3f2e40607229ccc3d6e) Thanks [@esengine](https://github.com/esengine)! - fix(node-editor): 修复节点收缩后连线不显示的问题
+    - 节点收缩时，连线会连接到节点头部（输入引脚在左侧，输出引脚在右侧）
+    - 展开后连线会自动恢复到正确位置
+
+## 1.2.1
+
+### Patch Changes
+
+- [#433](https://github.com/esengine/esengine/pull/433) [`2e84942`](https://github.com/esengine/esengine/commit/2e84942ea14c5326620398add05840fa8bea16f8) Thanks [@esengine](https://github.com/esengine)! - fix(node-editor): 修复节点收缩后连线不显示的问题
+    - 节点收缩时，连线会连接到节点头部（输入引脚在左侧，输出引脚在右侧）
+    - 展开后连线会自动恢复到正确位置
+
+## 1.2.0
+
+### Minor Changes
+
+- [#430](https://github.com/esengine/esengine/pull/430) [`caf3be7`](https://github.com/esengine/esengine/commit/caf3be72cdcc730492c63abe5f1715893f3579ac) Thanks [@esengine](https://github.com/esengine)! - feat(node-editor): 添加 Shadow DOM 样式注入支持 | Add Shadow DOM style injection support
+
+    **@esengine/node-editor**
+    - 新增 `nodeEditorCssText` 导出，包含所有编辑器样式的 CSS 文本 | Added `nodeEditorCssText` export containing all editor styles as CSS text
+    - 新增 `injectNodeEditorStyles(root)` 函数，支持将样式注入到 Shadow DOM | Added `injectNodeEditorStyles(root)` function for injecting styles into Shadow DOM
+    - 支持在 Cocos Creator 等使用 Shadow DOM 的环境中使用 | Support usage in Shadow DOM environments like Cocos Creator
+
+## 1.1.0
+
+### Minor Changes
+
+- [#426](https://github.com/esengine/esengine/pull/426) [`6970394`](https://github.com/esengine/esengine/commit/6970394717ab8f743b0a41e248e3404a3b6fc7dc) Thanks [@esengine](https://github.com/esengine)! - feat: 独立发布节点编辑器 | Standalone node editor release
+    - 移动到 packages/devtools 目录 | Move to packages/devtools directory
+    - 清理依赖，使包可独立使用 | Clean dependencies for standalone use
+    - 可用于 Cocos Creator / LayaAir 插件开发 | Available for Cocos/Laya plugin development

packages/devtools/node-editor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esengine/node-editor",
-  "version": "1.0.0",
+  "version": "1.2.2",
   "description": "Universal node-based visual editor for blueprint, shader graph, and state machine",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -9,7 +9,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     },
     "./styles": {
       "import": "./dist/styles/index.css"
@@ -30,17 +31,18 @@
     "blueprint",
     "shader-graph",
     "state-machine",
-    "ecs",
-    "game-engine"
+    "react"
   ],
-  "author": "yhh",
+  "author": "ESEngine Team",
   "license": "MIT",
+  "peerDependencies": {
+    "react": "^18.0.0"
+  },
   "devDependencies": {
-    "react": "^18.3.1",
-    "zustand": "^5.0.8",
     "@types/node": "^20.19.17",
     "@types/react": "^18.3.12",
     "@vitejs/plugin-react": "^4.7.0",
+    "react": "^18.3.1",
     "rimraf": "^5.0.0",
     "typescript": "^5.8.3",
     "vite": "^6.0.7",
@@ -56,7 +58,6 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/esengine/esengine.git",
-    "directory": "packages/node-editor"
-  },
-  "private": true
+    "directory": "packages/devtools/node-editor"
+  }
 }

packages/devtools/node-editor/src/components/editor/NodeEditor.tsx

@@ -1,4 +1,4 @@
-import React, { useRef, useCallback, useState, useMemo } from 'react';
+import React, { useRef, useCallback, useState, useMemo, useEffect } from 'react';
 import { Graph } from '../../domain/models/Graph';
 import { GraphNode, NodeTemplate } from '../../domain/models/GraphNode';
 import { Connection } from '../../domain/models/Connection';
@@ -127,6 +127,25 @@ export const NodeEditor: React.FC<NodeEditorProps> = ({
     const [connectionDrag, setConnectionDrag] = useState<ConnectionDragState | null>(null);
     const [hoveredPin, setHoveredPin] = useState<Pin | null>(null);
 
+    // Force re-render after mount to ensure connections are drawn correctly
+    // 挂载后强制重渲染以确保连接线正确绘制
+    const [, forceUpdate] = useState(0);
+
+    // Track collapsed state to force connection re-render
+    // 跟踪折叠状态以强制连接线重渲染
+    const collapsedNodesKey = useMemo(() => {
+        return graph.nodes.map(n => `${n.id}:${n.isCollapsed}`).join(',');
+    }, [graph.nodes]);
+
+    useEffect(() => {
+        // Use requestAnimationFrame to wait for DOM to be fully rendered
+        // 使用 requestAnimationFrame 等待 DOM 完全渲染
+        const rafId = requestAnimationFrame(() => {
+            forceUpdate(n => n + 1);
+        });
+        return () => cancelAnimationFrame(rafId);
+    }, [graph.id, collapsedNodesKey]);
+
     /**
      * Converts screen coordinates to canvas coordinates
      * 将屏幕坐标转换为画布坐标
@@ -146,21 +165,51 @@ export const NodeEditor: React.FC<NodeEditorProps> = ({
      * 获取引脚在画布坐标系中的位置
      *
      * 直接从节点位置和引脚在节点内的相对位置计算，不依赖 DOM 测量
+     * 当节点收缩时，返回节点头部的位置
      */
     const getPinPosition = useCallback((pinId: string): Position | undefined => {
+        // First, find which node this pin belongs to
+        // 首先查找该引脚属于哪个节点
+        let ownerNode: GraphNode | undefined;
+        for (const node of graph.nodes) {
+            if (node.allPins.some(p => p.id === pinId)) {
+                ownerNode = node;
+                break;
+            }
+        }
+        if (!ownerNode) return undefined;
+
         // Find the pin element and its parent node
         const pinElement = containerRef.current?.querySelector(`[data-pin-id="${pinId}"]`) as HTMLElement;
-        if (!pinElement) return undefined;
+
+        // If pin element not found (e.g., node is collapsed), use node header position
+        // 如果找不到引脚元素（例如节点已收缩），使用节点头部位置
+        if (!pinElement) {
+            const nodeElement = containerRef.current?.querySelector(`[data-node-id="${ownerNode.id}"]`) as HTMLElement;
+            if (!nodeElement) return undefined;
+
+            const nodeRect = nodeElement.getBoundingClientRect();
+            const { zoom } = transformRef.current;
+
+            // Find the pin to determine if it's input or output
+            const pin = ownerNode.allPins.find(p => p.id === pinId);
+            const isOutput = pin?.isOutput ?? false;
+
+            // For collapsed nodes, position at the right side for outputs, left side for inputs
+            // 对于收缩的节点，输出引脚在右侧，输入引脚在左侧
+            const headerHeight = 28; // Approximate header height
+            const relativeX = isOutput ? nodeRect.width / zoom : 0;
+            const relativeY = headerHeight / 2;
+
+            return new Position(
+                ownerNode.position.x + relativeX,
+                ownerNode.position.y + relativeY
+            );
+        }
 
         const nodeElement = pinElement.closest('[data-node-id]') as HTMLElement;
         if (!nodeElement) return undefined;
 
-        const nodeId = nodeElement.getAttribute('data-node-id');
-        if (!nodeId) return undefined;
-
-        const node = graph.getNode(nodeId);
-        if (!node) return undefined;
-
         // Get pin position relative to node element (in unscaled pixels)
         const nodeRect = nodeElement.getBoundingClientRect();
         const pinRect = pinElement.getBoundingClientRect();
@@ -172,8 +221,8 @@ export const NodeEditor: React.FC<NodeEditorProps> = ({
 
         // Final position = node position + relative position
         return new Position(
-            node.position.x + relativeX,
-            node.position.y + relativeY
+            ownerNode.position.x + relativeX,
+            ownerNode.position.y + relativeY
         );
     }, [graph]);
 

packages/devtools/node-editor/src/index.ts

@@ -10,6 +10,9 @@
 // Import styles (导入样式)
 import './styles/index.css';
 
+// CSS utilities for Shadow DOM (Shadow DOM 的 CSS 工具)
+export { nodeEditorCssText, injectNodeEditorStyles } from './styles/cssText';
+
 // Domain models (领域模型)
 export {
     // Models

packages/devtools/node-editor/src/styles/cssText.ts

@@ -0,0 +1,55 @@
+/**
+ * @zh 节点编辑器 CSS 样式文本
+ * @en Node Editor CSS style text
+ *
+ * @zh 此文件在构建时由 vite 插件自动生成
+ * @en This file is auto-generated by vite plugin during build
+ */
+
+// Placeholder - will be replaced by vite plugin during build
+export const nodeEditorCssText = '__NODE_EDITOR_CSS_PLACEHOLDER__';
+
+/**
+ * @zh 将 CSS 注入到指定的根节点（支持 Shadow DOM）
+ * @en Inject CSS into specified root node (supports Shadow DOM)
+ *
+ * @param root - @zh 目标根节点（Document 或 ShadowRoot）@en Target root node (Document or ShadowRoot)
+ * @param styleId - @zh 样式标签的 ID @en ID for the style tag
+ * @returns @zh 创建的 style 元素 @en The created style element
+ *
+ * @example
+ * ```typescript
+ * // Inject into Shadow DOM
+ * const shadowRoot = element.attachShadow({ mode: 'open' });
+ * injectNodeEditorStyles(shadowRoot);
+ *
+ * // Inject into document (with custom ID)
+ * injectNodeEditorStyles(document, 'my-editor-styles');
+ * ```
+ */
+export function injectNodeEditorStyles(
+    root: Document | ShadowRoot | DocumentFragment,
+    styleId: string = 'esengine-node-editor-styles'
+): HTMLStyleElement | null {
+    // Check if already injected
+    const existingStyle = (root as any).getElementById?.(styleId) ||
+        (root as any).querySelector?.(`#${styleId}`);
+    if (existingStyle) {
+        return existingStyle as HTMLStyleElement;
+    }
+
+    // Create and inject style element
+    const style = document.createElement('style');
+    style.id = styleId;
+    style.textContent = nodeEditorCssText;
+
+    if ('head' in root) {
+        // Document
+        (root as Document).head.appendChild(style);
+    } else {
+        // ShadowRoot or DocumentFragment
+        root.appendChild(style);
+    }
+
+    return style;
+}

packages/devtools/node-editor/vite.config.ts

@@ -4,12 +4,14 @@ import dts from 'vite-plugin-dts';
 import react from '@vitejs/plugin-react';
 
 /**
- * Custom plugin: Convert CSS to self-executing style injection code
- * 自定义插件：将 CSS 转换为自执行的样式注入代码
+ * Custom plugin: Handle CSS for node editor
+ * 自定义插件：处理节点编辑器的 CSS
+ *
+ * This plugin does two things:
+ * 1. Auto-injects CSS into document.head for normal usage
+ * 2. Replaces placeholder in cssText.ts with actual CSS for Shadow DOM usage
  */
 function injectCSSPlugin(): any {
-    let cssCounter = 0;
-
     return {
         name: 'inject-css-plugin',
         enforce: 'post' as const,
@@ -23,19 +25,28 @@ function injectCSSPlugin(): any {
                 const cssChunk = bundle[cssFile];
                 if (!cssChunk || !cssChunk.source) continue;
 
-                const cssContent = cssChunk.source;
-                const styleId = `esengine-node-editor-style-${cssCounter++}`;
+                const cssContent = cssChunk.source as string;
+                const styleId = 'esengine-node-editor-styles';
 
                 // Generate style injection code (生成样式注入代码)
                 const injectCode = `(function(){if(typeof document!=='undefined'){var s=document.createElement('style');s.id='${styleId}';if(!document.getElementById(s.id)){s.textContent=${JSON.stringify(cssContent)};document.head.appendChild(s);}}})();`;
 
-                // Inject into index.js (注入到 index.js)
+                // Process all JS bundles (处理所有 JS 包)
                 for (const jsKey of bundleKeys) {
-                    if (!jsKey.endsWith('.js')) continue;
+                    if (!jsKey.endsWith('.js') && !jsKey.endsWith('.cjs')) continue;
                     const jsChunk = bundle[jsKey];
                     if (!jsChunk || jsChunk.type !== 'chunk' || !jsChunk.code) continue;
 
-                    if (jsKey === 'index.js') {
+                    // Replace CSS placeholder with actual CSS content
+                    // 将 CSS 占位符替换为实际的 CSS 内容
+                    // Match both single and double quotes (ESM uses single, CJS uses double)
+                    jsChunk.code = jsChunk.code.replace(
+                        /['"]__NODE_EDITOR_CSS_PLACEHOLDER__['"]/g,
+                        JSON.stringify(cssContent)
+                    );
+
+                    // Auto-inject CSS for index bundles (为 index 包自动注入 CSS)
+                    if (jsKey === 'index.js' || jsKey === 'index.cjs') {
                         jsChunk.code = injectCode + '\n' + jsChunk.code;
                     }
                 }
@@ -65,8 +76,11 @@ export default defineConfig({
             entry: {
                 index: resolve(__dirname, 'src/index.ts')
             },
-            formats: ['es'],
-            fileName: (format, entryName) => `${entryName}.js`
+            formats: ['es', 'cjs'],
+            fileName: (format, entryName) => {
+                if (format === 'cjs') return `${entryName}.cjs`;
+                return `${entryName}.js`;
+            }
         },
         rollupOptions: {
             external: [

packages/editor/editor-app/README.md

@@ -0,0 +1,132 @@
+# 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 and WASM builds)
+- **wasm-pack** (for building Rapier2D physics engine)
+- **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)
+
+### Installing wasm-pack
+
+```bash
+# Using cargo
+cargo install wasm-pack
+
+# Or using the official installer script (Linux/macOS)
+curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+```
+
+## Quick Start
+
+### 1. Clone and Install
+
+```bash
+git clone https://github.com/esengine/esengine.git
+cd esengine
+pnpm install
+```
+
+### 2. Build Rapier2D WASM
+
+The editor depends on Rapier2D physics engine WASM artifacts. First-time setup only requires one command:
+
+```bash
+pnpm build:rapier2d
+```
+
+This command automatically:
+1. Prepares the Rust project
+2. Builds WASM
+3. Copies artifacts to `packages/physics/rapier2d/pkg`
+4. Generates TypeScript source code
+
+> **Note**: Requires Rust and wasm-pack to be installed.
+
+### 3. Build Editor
+
+From the project root:
+
+```bash
+pnpm build:editor
+```
+
+### 4. Run Editor
+
+```bash
+cd packages/editor/editor-app
+pnpm tauri:dev
+```
+
+## Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `pnpm build:rapier2d` | Build Rapier2D WASM (required for first-time setup) |
+| `pnpm build:editor` | Build editor and all dependencies |
+| `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
+
+### Rapier2D WASM Build Failed
+
+**Error**: `Could not resolve "../pkg/rapier_wasm2d"`
+
+**Cause**: Missing Rapier2D WASM artifacts.
+
+**Solution**:
+1. Ensure `wasm-pack` is installed: `cargo install wasm-pack`
+2. Run `pnpm build:rapier2d`
+3. Verify `packages/physics/rapier2d/pkg/` directory exists and contains `rapier_wasm2d_bg.wasm` file
+
+### Build Errors
+
+```bash
+pnpm clean
+pnpm install
+pnpm build:editor
+```
+
+### Rust/Tauri Errors
+
+```bash
+rustup update
+```
+
+### Windows Users Building WASM
+
+The `pnpm build:rapier2d` script works directly on Windows. If you encounter issues:
+1. Use Git Bash or WSL
+2. Or download pre-built WASM artifacts from [Releases](https://github.com/esengine/esengine/releases)
+
+## Documentation
+
+- [ESEngine Documentation](https://esengine.cn/)
+- [Tauri Documentation](https://tauri.app/)
+
+## License
+
+MIT License

packages/editor/editor-app/README_CN.md

@@ -0,0 +1,132 @@
+# ESEngine 编辑器
+
+基于 Tauri 2.x + React 18 构建的跨平台桌面可视化编辑器。
+
+## 环境要求
+
+运行编辑器前，请确保已安装以下环境：
+
+- **Node.js** >= 18.x
+- **pnpm** >= 10.x
+- **Rust** >= 1.70 (Tauri 和 WASM 构建需要)
+- **wasm-pack** (构建 Rapier2D 物理引擎需要)
+- **平台相关依赖**：
+  - **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)
+
+### 安装 wasm-pack
+
+```bash
+# 使用 cargo 安装
+cargo install wasm-pack
+
+# 或使用官方安装脚本 (Linux/macOS)
+curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+```
+
+## 快速开始
+
+### 1. 克隆并安装
+
+```bash
+git clone https://github.com/esengine/esengine.git
+cd esengine
+pnpm install
+```
+
+### 2. 构建 Rapier2D WASM
+
+编辑器依赖 Rapier2D 物理引擎的 WASM 产物。首次构建只需执行一条命令：
+
+```bash
+pnpm build:rapier2d
+```
+
+该命令会自动完成以下步骤：
+1. 准备 Rust 项目
+2. 构建 WASM
+3. 复制产物到 `packages/physics/rapier2d/pkg`
+4. 生成 TypeScript 源码
+
+> **注意**：需要已安装 Rust 和 wasm-pack。
+
+### 3. 构建编辑器
+
+在项目根目录执行：
+
+```bash
+pnpm build:editor
+```
+
+### 4. 启动编辑器
+
+```bash
+cd packages/editor/editor-app
+pnpm tauri:dev
+```
+
+## 可用脚本
+
+| 脚本 | 说明 |
+|------|------|
+| `pnpm build:rapier2d` | 构建 Rapier2D WASM（首次构建必须执行）|
+| `pnpm build:editor` | 构建编辑器及所有依赖 |
+| `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/                # 构建脚本
+```
+
+## 常见问题
+
+### Rapier2D WASM 构建失败
+
+**错误**: `Could not resolve "../pkg/rapier_wasm2d"`
+
+**原因**: 缺少 Rapier2D 的 WASM 产物。
+
+**解决方案**:
+1. 确保已安装 `wasm-pack`：`cargo install wasm-pack`
+2. 执行 `pnpm build:rapier2d`
+3. 确认 `packages/physics/rapier2d/pkg/` 目录存在且包含 `rapier_wasm2d_bg.wasm` 文件
+
+### 构建错误
+
+```bash
+pnpm clean
+pnpm install
+pnpm build:editor
+```
+
+### Rust/Tauri 错误
+
+```bash
+rustup update
+```
+
+### Windows 用户构建 WASM
+
+`pnpm build:rapier2d` 脚本在 Windows 上可以直接运行。如果遇到问题：
+1. 使用 Git Bash 或 WSL
+2. 或从 [Releases](https://github.com/esengine/esengine/releases) 下载预编译的 WASM 产物
+
+## 文档
+
+- [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';