chore: release packages (#409)

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

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/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/server.md

@@ -79,10 +79,140 @@ 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.
+
+### File-based Routing
+
+Create route files in the `httpDir` directory, automatically mapped to HTTP endpoints:
+
+```
+src/http/
+├── login.ts       → POST /api/login
+├── register.ts    → POST /api/register
+├── health.ts      → GET  /api/health (set method: 'GET')
+└── users/
+    └── [id].ts    → POST /api/users/:id (dynamic route)
+```
+
+### Define Routes
+
+Use `defineHttp` to define type-safe route handlers:
+
+```typescript
+// src/http/login.ts
+import { defineHttp } from '@esengine/server'
+
+interface LoginBody {
+    username: string
+    password: string
+}
+
+export default defineHttp<LoginBody>({
+    method: 'POST',  // Default POST, options: GET/PUT/DELETE/PATCH
+    handler(req, res) {
+        const { username, password } = req.body
+
+        // Validate credentials...
+        if (!isValid(username, password)) {
+            res.error(401, 'Invalid credentials')
+            return
+        }
+
+        // Generate token...
+        res.json({ token: '...', userId: '...' })
+    }
+})
+```
+
+### Request Object (HttpRequest)
+
+```typescript
+interface HttpRequest {
+    raw: IncomingMessage     // Node.js raw request
+    method: string           // Request method
+    path: string             // Request path
+    query: Record<string, string>  // Query parameters
+    headers: Record<string, string | string[] | undefined>
+    body: unknown            // Parsed JSON body
+    ip: string               // Client IP
+}
+```
+
+### Response Object (HttpResponse)
+
+```typescript
+interface HttpResponse {
+    raw: ServerResponse      // Node.js raw response
+    status(code: number): HttpResponse   // Set status code (chainable)
+    header(name: string, value: string): HttpResponse  // Set header (chainable)
+    json(data: unknown): void            // Send JSON
+    text(data: string): void             // Send text
+    error(code: number, message: string): void  // Send error
+}
+```
+
+### Usage Example
+
+```typescript
+// Complete login server example
+import { createServer, defineHttp } from '@esengine/server'
+import { createJwtAuthProvider, withAuth } from '@esengine/server/auth'
+
+const jwtProvider = createJwtAuthProvider({
+    secret: process.env.JWT_SECRET!,
+    expiresIn: 3600 * 24,
+})
+
+const server = await createServer({
+    port: 8080,
+    httpDir: 'src/http',
+    httpPrefix: '/api',
+    cors: true,
+})
+
+// Wrap with auth (WebSocket connections validate token)
+const authServer = withAuth(server, {
+    provider: jwtProvider,
+    extractCredentials: (req) => {
+        const url = new URL(req.url, 'http://localhost')
+        return url.searchParams.get('token')
+    },
+})
+
+await authServer.start()
+// HTTP: http://localhost:8080/api/*
+// WebSocket: ws://localhost:8080?token=xxx
+```
+
+### Inline Routes
+
+Routes can also be defined directly in configuration (merged with file routes, inline takes priority):
+
+```typescript
+const server = await createServer({
+    port: 8080,
+    http: {
+        '/health': {
+            GET: (req, res) => res.json({ status: 'ok' }),
+        },
+        '/webhook': async (req, res) => {
+            // Accepts all methods
+            await handleWebhook(req.body)
+            res.json({ received: true })
+        },
+    },
+})
+```
+
 ## Room System
 
 Room is the base class for game rooms, managing players and game state.

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/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/server.md

@@ -79,10 +79,140 @@ 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 共用端口，适用于登录、注册等场景。
+
+### 文件路由
+
+在 `httpDir` 目录下创建路由文件，自动映射为 HTTP 端点：
+
+```
+src/http/
+├── login.ts       → POST /api/login
+├── register.ts    → POST /api/register
+├── health.ts      → GET  /api/health (需设置 method: 'GET')
+└── users/
+    └── [id].ts    → POST /api/users/:id (动态路由)
+```
+
+### 定义路由
+
+使用 `defineHttp` 定义类型安全的路由处理器：
+
+```typescript
+// src/http/login.ts
+import { defineHttp } from '@esengine/server'
+
+interface LoginBody {
+    username: string
+    password: string
+}
+
+export default defineHttp<LoginBody>({
+    method: 'POST',  // 默认 POST，可选 GET/PUT/DELETE/PATCH
+    handler(req, res) {
+        const { username, password } = req.body
+
+        // 验证凭证...
+        if (!isValid(username, password)) {
+            res.error(401, 'Invalid credentials')
+            return
+        }
+
+        // 生成 token...
+        res.json({ token: '...', userId: '...' })
+    }
+})
+```
+
+### 请求对象 (HttpRequest)
+
+```typescript
+interface HttpRequest {
+    raw: IncomingMessage     // Node.js 原始请求
+    method: string           // 请求方法
+    path: string             // 请求路径
+    query: Record<string, string>  // 查询参数
+    headers: Record<string, string | string[] | undefined>
+    body: unknown            // 解析后的 JSON 请求体
+    ip: string               // 客户端 IP
+}
+```
+
+### 响应对象 (HttpResponse)
+
+```typescript
+interface HttpResponse {
+    raw: ServerResponse      // Node.js 原始响应
+    status(code: number): HttpResponse   // 设置状态码（链式）
+    header(name: string, value: string): HttpResponse  // 设置头（链式）
+    json(data: unknown): void            // 发送 JSON
+    text(data: string): void             // 发送文本
+    error(code: number, message: string): void  // 发送错误
+}
+```
+
+### 使用示例
+
+```typescript
+// 完整的登录服务器示例
+import { createServer, defineHttp } from '@esengine/server'
+import { createJwtAuthProvider, withAuth } from '@esengine/server/auth'
+
+const jwtProvider = createJwtAuthProvider({
+    secret: process.env.JWT_SECRET!,
+    expiresIn: 3600 * 24,
+})
+
+const server = await createServer({
+    port: 8080,
+    httpDir: 'src/http',
+    httpPrefix: '/api',
+    cors: true,
+})
+
+// 包装认证（WebSocket 连接验证 token）
+const authServer = withAuth(server, {
+    provider: jwtProvider,
+    extractCredentials: (req) => {
+        const url = new URL(req.url, 'http://localhost')
+        return url.searchParams.get('token')
+    },
+})
+
+await authServer.start()
+// HTTP: http://localhost:8080/api/*
+// WebSocket: ws://localhost:8080?token=xxx
+```
+
+### 内联路由
+
+也可以直接在配置中定义路由（与文件路由合并，内联优先）：
+
+```typescript
+const server = await createServer({
+    port: 8080,
+    http: {
+        '/health': {
+            GET: (req, res) => res.json({ status: 'ok' }),
+        },
+        '/webhook': async (req, res) => {
+            // 接受所有方法
+            await handleWebhook(req.body)
+            res.json({ received: true })
+        },
+    },
+})
+```
+
 ## Room 系统
 
 Room 是游戏房间的基类，管理玩家和游戏状态。

package.json

@@ -74,6 +74,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/editor/editor-app/README.md

@@ -8,12 +8,23 @@ Before running the editor, ensure you have the following installed:
 
 - **Node.js** >= 18.x
 - **pnpm** >= 10.x
-- **Rust** >= 1.70 (for Tauri)
+- **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
@@ -24,7 +35,23 @@ cd esengine
 pnpm install
 ```
 
-### 2. Build Dependencies
+### 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:
 
@@ -32,7 +59,7 @@ From the project root:
 pnpm build:editor
 ```
 
-### 3. Run Editor
+### 4. Run Editor
 
 ```bash
 cd packages/editor/editor-app
@@ -43,6 +70,8 @@ pnpm tauri:dev
 
 | 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 |
@@ -62,6 +91,17 @@ editor-app/
 
 ## 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
@@ -76,6 +116,12 @@ pnpm build:editor
 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/)

packages/editor/editor-app/README_CN.md

@@ -8,12 +8,23 @@
 
 - **Node.js** >= 18.x
 - **pnpm** >= 10.x
-- **Rust** >= 1.70 (Tauri 需要)
+- **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. 克隆并安装
@@ -24,7 +35,23 @@ cd esengine
 pnpm install
 ```
 
-### 2. 构建依赖
+### 2. 构建 Rapier2D WASM
+
+编辑器依赖 Rapier2D 物理引擎的 WASM 产物。首次构建只需执行一条命令：
+
+```bash
+pnpm build:rapier2d
+```
+
+该命令会自动完成以下步骤：
+1. 准备 Rust 项目
+2. 构建 WASM
+3. 复制产物到 `packages/physics/rapier2d/pkg`
+4. 生成 TypeScript 源码
+
+> **注意**：需要已安装 Rust 和 wasm-pack。
+
+### 3. 构建编辑器
 
 在项目根目录执行：
 
@@ -32,7 +59,7 @@ pnpm install
 pnpm build:editor
 ```
 
-### 3. 启动编辑器
+### 4. 启动编辑器
 
 ```bash
 cd packages/editor/editor-app
@@ -43,6 +70,8 @@ pnpm tauri:dev
 
 | 脚本 | 说明 |
 |------|------|
+| `pnpm build:rapier2d` | 构建 Rapier2D WASM（首次构建必须执行）|
+| `pnpm build:editor` | 构建编辑器及所有依赖 |
 | `pnpm tauri:dev` | 开发模式运行编辑器（支持热重载）|
 | `pnpm tauri:build` | 构建生产版本应用 |
 | `pnpm build:sdk` | 构建 editor-runtime SDK |
@@ -62,6 +91,17 @@ editor-app/
 
 ## 常见问题
 
+### 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
@@ -76,6 +116,12 @@ pnpm build:editor
 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/)

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

@@ -8,7 +8,10 @@
         "rootDir": "./src",
         "jsx": "react-jsx",
         "skipLibCheck": true,
-        "moduleResolution": "bundler"
+        "moduleResolution": "bundler",
+        "paths": {
+            "@esengine/asset-system": ["../../../engine/asset-system/src"]
+        }
     },
     "include": ["src/**/*"],
     "exclude": ["node_modules", "dist", "**/*.test.ts"]

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

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

packages/framework/behavior-tree/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @esengine/behavior-tree
 
+## 4.2.0
+
+### Minor Changes
+
+- [#408](https://github.com/esengine/esengine/pull/408) [`b9ea8d1`](https://github.com/esengine/esengine/commit/b9ea8d14cf38e1480f638c229f9ee150b65f0c60) Thanks [@esengine](https://github.com/esengine)! - feat: add action() and condition() methods to BehaviorTreeBuilder
+
+    Added new methods to support custom executor types directly in the builder:
+    - `action(implementationType, name?, config?)` - Use custom action executors registered via `@NodeExecutorMetadata`
+    - `condition(implementationType, name?, config?)` - Use custom condition executors
+
+    This provides a cleaner API for using custom node executors compared to the existing `executeAction()` which only supports blackboard functions.
+
+    Example:
+
+    ```typescript
+    // Define custom executor
+    @NodeExecutorMetadata({
+        implementationType: 'AttackAction',
+        nodeType: NodeType.Action,
+        displayName: 'Attack',
+        category: 'Combat'
+    })
+    class AttackAction implements INodeExecutor {
+        execute(context: NodeExecutionContext): TaskStatus {
+            return TaskStatus.Success;
+        }
+    }
+
+    // Use in builder
+    const tree = BehaviorTreeBuilder.create('AI')
+        .selector('Root')
+        .action('AttackAction', 'Attack', { damage: 50 })
+        .end()
+        .build();
+    ```
+
+## 4.1.2
+
+### Patch Changes
+
+- [#406](https://github.com/esengine/esengine/pull/406) [`0de4527`](https://github.com/esengine/esengine/commit/0de45279e612c04ae9be7fbd65ce496e4797a43c) Thanks [@esengine](https://github.com/esengine)! - fix(behavior-tree): export NodeExecutorMetadata as value instead of type
+
+    Fixed the export of `NodeExecutorMetadata` decorator in `execution/index.ts`.
+    Previously it was exported as `export type { NodeExecutorMetadata }` which only
+    exported the type signature, not the actual function. This caused runtime errors
+    in Cocos Creator: "TypeError: (intermediate value) is not a function".
+
+    Changed to `export { NodeExecutorMetadata }` to properly export the decorator function.
+
 ## 4.1.1
 
 ### Patch Changes

packages/framework/behavior-tree/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@esengine/behavior-tree",
-    "version": "4.1.1",
+    "version": "4.2.0",
     "description": "ECS-based AI behavior tree system - works with any ECS framework (ESEngine, Cocos, Laya, etc.)",
     "main": "dist/index.js",
     "module": "dist/index.js",
@@ -29,7 +29,8 @@
         "clean": "rimraf dist tsconfig.tsbuildinfo",
         "build": "tsup",
         "build:watch": "tsup --watch",
-        "type-check": "tsc --noEmit"
+        "type-check": "tsc --noEmit",
+        "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
     },
     "author": "yhh",
     "license": "MIT",

packages/framework/behavior-tree/src/BehaviorTreeBuilder.ts

@@ -181,12 +181,73 @@ export class BehaviorTreeBuilder {
     }
 
     /**
-     * 添加执行动作
+     * 添加执行动作（通过黑板函数）
+     *
+     * @zh 使用黑板中的 action_{actionName} 函数执行动作
+     * @en Execute action using action_{actionName} function from blackboard
+     *
+     * @example
+     * ```typescript
+     * BehaviorTreeBuilder.create("AI")
+     *     .defineBlackboardVariable("action_Attack", (entity) => TaskStatus.Success)
+     *     .selector("Root")
+     *         .executeAction("Attack")
+     *     .end()
+     *     .build();
+     * ```
      */
     executeAction(actionName: string, name?: string): BehaviorTreeBuilder {
         return this.addActionNode('ExecuteAction', name || 'ExecuteAction', { actionName });
     }
 
+    /**
+     * 添加自定义动作节点
+     *
+     * @zh 直接使用注册的执行器类型（通过 @NodeExecutorMetadata 装饰器注册的类）
+     * @en Use a registered executor type directly (class registered via @NodeExecutorMetadata decorator)
+     *
+     * @param implementationType - 执行器类型名称（@NodeExecutorMetadata 中的 implementationType）
+     * @param name - 节点显示名称
+     * @param config - 节点配置参数
+     *
+     * @example
+     * ```typescript
+     * // 1. 定义自定义执行器
+     * @NodeExecutorMetadata({
+     *     implementationType: 'AttackAction',
+     *     nodeType: NodeType.Action,
+     *     displayName: '攻击动作',
+     *     category: 'Action'
+     * })
+     * class AttackAction implements INodeExecutor {
+     *     execute(context: NodeExecutionContext): TaskStatus {
+     *         console.log("执行攻击！");
+     *         return TaskStatus.Success;
+     *     }
+     * }
+     *
+     * // 2. 在行为树中使用
+     * BehaviorTreeBuilder.create("AI")
+     *     .selector("Root")
+     *         .action("AttackAction", "Attack")
+     *     .end()
+     *     .build();
+     * ```
+     */
+    action(implementationType: string, name?: string, config?: Record<string, any>): BehaviorTreeBuilder {
+        return this.addActionNode(implementationType, name || implementationType, config || {});
+    }
+
+    /**
+     * 添加自定义条件节点
+     *
+     * @zh 直接使用注册的条件执行器类型
+     * @en Use a registered condition executor type directly
+     */
+    condition(implementationType: string, name?: string, config?: Record<string, any>): BehaviorTreeBuilder {
+        return this.addConditionNode(implementationType, name || implementationType, config || {});
+    }
+
     /**
      * 添加黑板比较条件
      */

packages/framework/behavior-tree/src/execution/index.ts

@@ -5,7 +5,7 @@ export { BehaviorTreeAssetManager } from './BehaviorTreeAssetManager';
 export type { INodeExecutor, NodeExecutionContext } from './NodeExecutor';
 export { NodeExecutorRegistry, BindingHelper } from './NodeExecutor';
 export { BehaviorTreeExecutionSystem } from './BehaviorTreeExecutionSystem';
-export type { NodeMetadata, ConfigFieldDefinition, NodeExecutorMetadata } from './NodeMetadata';
-export { NodeMetadataRegistry } from './NodeMetadata';
+export type { NodeMetadata, ConfigFieldDefinition } from './NodeMetadata';
+export { NodeMetadataRegistry, NodeExecutorMetadata } from './NodeMetadata';
 
 export * from './Executors';

packages/framework/network/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @esengine/network
 
+## 5.0.3
+
+### Patch Changes
+
+- Updated dependencies [[`902c0a1`](https://github.com/esengine/esengine/commit/902c0a10749f80bd8f499b44154646379d359704)]:
+    - @esengine/rpc@1.1.3
+
+## 5.0.2
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/rpc@1.1.2
+
 ## 5.0.1
 
 ### Patch Changes

packages/framework/network/package.json

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

packages/framework/rpc/CHANGELOG.md

@@ -1,5 +1,93 @@
 # @esengine/rpc
 
+## 1.1.3
+
+### Patch Changes
+
+- [#404](https://github.com/esengine/esengine/pull/404) [`902c0a1`](https://github.com/esengine/esengine/commit/902c0a10749f80bd8f499b44154646379d359704) Thanks [@esengine](https://github.com/esengine)! - feat(server): add HTTP file-based routing support / 添加 HTTP 文件路由支持
+
+    New feature that allows organizing HTTP routes in separate files, similar to API and message handlers.
+    新功能：支持将 HTTP 路由组织在独立文件中，类似于 API 和消息处理器的文件路由方式。
+
+    ```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;
+            res.json({ token: '...', userId: '...' });
+        }
+    });
+    ```
+
+    Server configuration / 服务器配置:
+
+    ```typescript
+    const server = await createServer({
+        port: 8080,
+        httpDir: 'src/http', // HTTP routes directory / HTTP 路由目录
+        httpPrefix: '/api', // Route prefix / 路由前缀
+        cors: true
+    });
+    ```
+
+    File naming convention / 文件命名规则:
+    - `login.ts` → POST /api/login
+    - `users/profile.ts` → POST /api/users/profile
+    - `users/[id].ts` → POST /api/users/:id (dynamic routes / 动态路由)
+    - Set `method: 'GET'` in defineHttp for GET requests / 在 defineHttp 中设置 `method: 'GET'` 以处理 GET 请求
+
+    Also includes / 还包括:
+    - `defineHttp<TBody>()` helper for type-safe route definitions / 类型安全的路由定义辅助函数
+    - Support for merging file routes with inline `http` config / 支持文件路由与内联 `http` 配置合并
+    - RPC server supports attaching to existing HTTP server via `server` option / RPC 服务器支持通过 `server` 选项附加到现有 HTTP 服务器
+
+## 1.1.2
+
+### Patch Changes
+
+- feat(server): add HTTP file-based routing support
+
+    New feature that allows organizing HTTP routes in separate files, similar to API and message handlers:
+
+    ```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;
+            // ... authentication logic
+            res.json({ token: '...', userId: '...' });
+        }
+    });
+    ```
+
+    Server configuration:
+
+    ```typescript
+    const server = await createServer({
+        port: 8080,
+        httpDir: 'src/http', // HTTP routes directory
+        httpPrefix: '/api', // Route prefix
+        cors: true
+    });
+    ```
+
+    File naming convention:
+    - `login.ts` → POST /api/login
+    - `users/profile.ts` → POST /api/users/profile
+    - `users/[id].ts` → POST /api/users/:id (dynamic routes)
+    - Set `method: 'GET'` in defineHttp for GET requests
+
+    Also includes:
+    - `defineHttp<TBody>()` helper function for type-safe route definitions
+    - Support for merging file routes with inline `http` config
+    - RPC server now supports attaching to existing HTTP server via `server` option
+
 ## 1.1.1
 
 ### Patch Changes

packages/framework/rpc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esengine/rpc",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Elegant type-safe RPC library for ESEngine",
   "type": "module",
   "main": "./dist/index.js",

packages/framework/rpc/src/server/index.ts

@@ -4,6 +4,7 @@
  */
 
 import { WebSocketServer, WebSocket } from 'ws'
+import type { Server as HttpServer } from 'node:http'
 import type {
     ProtocolDef,
     ApiNames,
@@ -66,10 +67,19 @@ type MsgHandlers<P extends ProtocolDef, TConnData> = {
  */
 export interface ServeOptions<P extends ProtocolDef, TConnData = unknown> {
     /**
-     * @zh 监听端口
-     * @en Listen port
+     * @zh 监听端口（与 server 二选一）
+     * @en Listen port (mutually exclusive with server)
      */
-    port: number
+    port?: number
+
+    /**
+     * @zh 已有的 HTTP 服务器（与 port 二选一）
+     * @en Existing HTTP server (mutually exclusive with port)
+     *
+     * @zh 使用此选项可以在同一端口同时支持 HTTP 和 WebSocket
+     * @en Use this option to support both HTTP and WebSocket on the same port
+     */
+    server?: HttpServer
 
     /**
      * @zh API 处理器
@@ -280,7 +290,16 @@ export function serve<P extends ProtocolDef, TConnData = unknown>(
 
         async start() {
             return new Promise((resolve) => {
-                wss = new WebSocketServer({ port: options.port })
+                // 根据配置创建 WebSocketServer
+                if (options.server) {
+                    // 附加到已有的 HTTP 服务器
+                    wss = new WebSocketServer({ server: options.server })
+                } else if (options.port) {
+                    // 独立创建
+                    wss = new WebSocketServer({ port: options.port })
+                } else {
+                    throw new Error('Either port or server must be provided')
+                }
 
                 wss.on('connection', async (ws, req) => {
                     const id = String(++connIdCounter)
@@ -318,10 +337,16 @@ export function serve<P extends ProtocolDef, TConnData = unknown>(
                     await options.onConnect?.(conn)
                 })
 
-                wss.on('listening', () => {
-                    options.onStart?.(options.port)
+                // 如果使用已有的 HTTP 服务器，WebSocketServer 不会触发 listening 事件
+                if (options.server) {
+                    options.onStart?.(0) // 端口由 HTTP 服务器管理
                     resolve()
-                })
+                } else {
+                    wss.on('listening', () => {
+                        options.onStart?.(options.port!)
+                        resolve()
+                    })
+                }
             })
         },
 

packages/framework/server/CHANGELOG.md

@@ -1,5 +1,103 @@
 # @esengine/server
 
+## 4.2.0
+
+### Minor Changes
+
+- [#404](https://github.com/esengine/esengine/pull/404) [`902c0a1`](https://github.com/esengine/esengine/commit/902c0a10749f80bd8f499b44154646379d359704) Thanks [@esengine](https://github.com/esengine)! - feat(server): add HTTP file-based routing support / 添加 HTTP 文件路由支持
+
+    New feature that allows organizing HTTP routes in separate files, similar to API and message handlers.
+    新功能：支持将 HTTP 路由组织在独立文件中，类似于 API 和消息处理器的文件路由方式。
+
+    ```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;
+            res.json({ token: '...', userId: '...' });
+        }
+    });
+    ```
+
+    Server configuration / 服务器配置:
+
+    ```typescript
+    const server = await createServer({
+        port: 8080,
+        httpDir: 'src/http', // HTTP routes directory / HTTP 路由目录
+        httpPrefix: '/api', // Route prefix / 路由前缀
+        cors: true
+    });
+    ```
+
+    File naming convention / 文件命名规则:
+    - `login.ts` → POST /api/login
+    - `users/profile.ts` → POST /api/users/profile
+    - `users/[id].ts` → POST /api/users/:id (dynamic routes / 动态路由)
+    - Set `method: 'GET'` in defineHttp for GET requests / 在 defineHttp 中设置 `method: 'GET'` 以处理 GET 请求
+
+    Also includes / 还包括:
+    - `defineHttp<TBody>()` helper for type-safe route definitions / 类型安全的路由定义辅助函数
+    - Support for merging file routes with inline `http` config / 支持文件路由与内联 `http` 配置合并
+    - RPC server supports attaching to existing HTTP server via `server` option / RPC 服务器支持通过 `server` 选项附加到现有 HTTP 服务器
+
+### Patch Changes
+
+- Updated dependencies [[`902c0a1`](https://github.com/esengine/esengine/commit/902c0a10749f80bd8f499b44154646379d359704)]:
+    - @esengine/rpc@1.1.3
+
+## 4.1.0
+
+### Minor Changes
+
+- feat(server): add HTTP file-based routing support
+
+    New feature that allows organizing HTTP routes in separate files, similar to API and message handlers:
+
+    ```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;
+            // ... authentication logic
+            res.json({ token: '...', userId: '...' });
+        }
+    });
+    ```
+
+    Server configuration:
+
+    ```typescript
+    const server = await createServer({
+        port: 8080,
+        httpDir: 'src/http', // HTTP routes directory
+        httpPrefix: '/api', // Route prefix
+        cors: true
+    });
+    ```
+
+    File naming convention:
+    - `login.ts` → POST /api/login
+    - `users/profile.ts` → POST /api/users/profile
+    - `users/[id].ts` → POST /api/users/:id (dynamic routes)
+    - Set `method: 'GET'` in defineHttp for GET requests
+
+    Also includes:
+    - `defineHttp<TBody>()` helper function for type-safe route definitions
+    - Support for merging file routes with inline `http` config
+    - RPC server now supports attaching to existing HTTP server via `server` option
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/rpc@1.1.2
+
 ## 4.0.0
 
 ### Patch Changes

packages/framework/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esengine/server",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Game server framework for ESEngine with file-based routing",
   "type": "module",
   "main": "./dist/index.js",

packages/framework/server/src/core/server.ts

@@ -4,6 +4,7 @@
  */
 
 import * as path from 'node:path'
+import { createServer as createHttpServer, type Server as HttpServer } from 'node:http'
 import { serve, type RpcServer } from '@esengine/rpc/server'
 import { rpc } from '@esengine/rpc'
 import type {
@@ -14,18 +15,23 @@ import type {
     MsgContext,
     LoadedApiHandler,
     LoadedMsgHandler,
+    LoadedHttpHandler,
 } from '../types/index.js'
-import { loadApiHandlers, loadMsgHandlers } from '../router/loader.js'
+import type { HttpRoutes, HttpHandler } from '../http/types.js'
+import { loadApiHandlers, loadMsgHandlers, loadHttpHandlers } from '../router/loader.js'
 import { RoomManager, type RoomClass, type Room } from '../room/index.js'
+import { createHttpRouter } from '../http/router.js'
 
 /**
  * @zh 默认配置
  * @en Default configuration
  */
-const DEFAULT_CONFIG: Required<Omit<ServerConfig, 'onStart' | 'onConnect' | 'onDisconnect'>> = {
+const DEFAULT_CONFIG: Required<Omit<ServerConfig, 'onStart' | 'onConnect' | 'onDisconnect' | 'http' | 'cors' | 'httpDir' | 'httpPrefix'>> & { httpDir: string; httpPrefix: string } = {
     port: 3000,
     apiDir: 'src/api',
     msgDir: 'src/msg',
+    httpDir: 'src/http',
+    httpPrefix: '/api',
     tickRate: 20,
 }
 
@@ -56,12 +62,53 @@ export async function createServer(config: ServerConfig = {}): Promise<GameServe
     const apiHandlers = await loadApiHandlers(path.resolve(cwd, opts.apiDir))
     const msgHandlers = await loadMsgHandlers(path.resolve(cwd, opts.msgDir))
 
+    // 加载 HTTP 文件路由
+    const httpDir = config.httpDir ?? opts.httpDir
+    const httpPrefix = config.httpPrefix ?? opts.httpPrefix
+    const httpHandlers = await loadHttpHandlers(path.resolve(cwd, httpDir), httpPrefix)
+
     if (apiHandlers.length > 0) {
         console.log(`[Server] Loaded ${apiHandlers.length} API handlers`)
     }
     if (msgHandlers.length > 0) {
         console.log(`[Server] Loaded ${msgHandlers.length} message handlers`)
     }
+    if (httpHandlers.length > 0) {
+        console.log(`[Server] Loaded ${httpHandlers.length} HTTP handlers`)
+    }
+
+    // 合并 HTTP 路由（文件路由 + 内联路由）
+    const mergedHttpRoutes: HttpRoutes = {}
+
+    // 先添加文件路由
+    for (const handler of httpHandlers) {
+        const existingRoute = mergedHttpRoutes[handler.route]
+        if (existingRoute && typeof existingRoute !== 'function') {
+            (existingRoute as Record<string, HttpHandler>)[handler.method] = handler.definition.handler
+        } else {
+            mergedHttpRoutes[handler.route] = {
+                [handler.method]: handler.definition.handler,
+            }
+        }
+    }
+
+    // 再添加内联路由（覆盖文件路由）
+    if (config.http) {
+        for (const [route, handlerOrMethods] of Object.entries(config.http)) {
+            if (typeof handlerOrMethods === 'function') {
+                mergedHttpRoutes[route] = handlerOrMethods
+            } else {
+                const existing = mergedHttpRoutes[route]
+                if (existing && typeof existing !== 'function') {
+                    Object.assign(existing, handlerOrMethods)
+                } else {
+                    mergedHttpRoutes[route] = handlerOrMethods
+                }
+            }
+        }
+    }
+
+    const hasHttpRoutes = Object.keys(mergedHttpRoutes).length > 0
 
     // 动态构建协议
     const apiDefs: Record<string, ReturnType<typeof rpc.api>> = {
@@ -90,6 +137,7 @@ export async function createServer(config: ServerConfig = {}): Promise<GameServe
     let currentTick = 0
     let tickInterval: ReturnType<typeof setInterval> | null = null
     let rpcServer: RpcServer<typeof protocol, Record<string, unknown>> | null = null
+    let httpServer: HttpServer | null = null
 
     // 房间管理器（立即初始化，以便 define() 可在 start() 前调用）
     const roomManager = new RoomManager((conn, type, data) => {
@@ -200,26 +248,68 @@ export async function createServer(config: ServerConfig = {}): Promise<GameServe
                 }
             }
 
-            rpcServer = serve(protocol, {
-                port: opts.port,
-                createConnData: () => ({}),
-                onStart: (p) => {
-                    console.log(`[Server] Started on ws://localhost:${p}`)
-                    opts.onStart?.(p)
-                },
-                onConnect: async (conn) => {
-                    await config.onConnect?.(conn as ServerConnection)
-                },
-                onDisconnect: async (conn) => {
-                    // 玩家断线时自动离开房间
-                    await roomManager?.leave(conn.id, 'disconnected')
-                    await config.onDisconnect?.(conn as ServerConnection)
-                },
-                api: apiHandlersObj as any,
-                msg: msgHandlersObj as any,
-            })
+            // 如果有 HTTP 路由，创建 HTTP 服务器
+            if (hasHttpRoutes) {
+                const httpRouter = createHttpRouter(mergedHttpRoutes, config.cors ?? true)
 
-            await rpcServer.start()
+                httpServer = createHttpServer(async (req, res) => {
+                    // 先尝试 HTTP 路由
+                    const handled = await httpRouter(req, res)
+                    if (!handled) {
+                        // 未匹配的请求返回 404
+                        res.statusCode = 404
+                        res.setHeader('Content-Type', 'application/json')
+                        res.end(JSON.stringify({ error: 'Not Found' }))
+                    }
+                })
+
+                // 使用 HTTP 服务器创建 RPC
+                rpcServer = serve(protocol, {
+                    server: httpServer,
+                    createConnData: () => ({}),
+                    onStart: () => {
+                        console.log(`[Server] Started on http://localhost:${opts.port}`)
+                        opts.onStart?.(opts.port)
+                    },
+                    onConnect: async (conn) => {
+                        await config.onConnect?.(conn as ServerConnection)
+                    },
+                    onDisconnect: async (conn) => {
+                        await roomManager?.leave(conn.id, 'disconnected')
+                        await config.onDisconnect?.(conn as ServerConnection)
+                    },
+                    api: apiHandlersObj as any,
+                    msg: msgHandlersObj as any,
+                })
+
+                await rpcServer.start()
+
+                // 启动 HTTP 服务器
+                await new Promise<void>((resolve) => {
+                    httpServer!.listen(opts.port, () => resolve())
+                })
+            } else {
+                // 仅 WebSocket 模式
+                rpcServer = serve(protocol, {
+                    port: opts.port,
+                    createConnData: () => ({}),
+                    onStart: (p) => {
+                        console.log(`[Server] Started on ws://localhost:${p}`)
+                        opts.onStart?.(p)
+                    },
+                    onConnect: async (conn) => {
+                        await config.onConnect?.(conn as ServerConnection)
+                    },
+                    onDisconnect: async (conn) => {
+                        await roomManager?.leave(conn.id, 'disconnected')
+                        await config.onDisconnect?.(conn as ServerConnection)
+                    },
+                    api: apiHandlersObj as any,
+                    msg: msgHandlersObj as any,
+                })
+
+                await rpcServer.start()
+            }
 
             // 启动 tick 循环
             if (opts.tickRate > 0) {
@@ -238,6 +328,15 @@ export async function createServer(config: ServerConfig = {}): Promise<GameServe
                 await rpcServer.stop()
                 rpcServer = null
             }
+            if (httpServer) {
+                await new Promise<void>((resolve, reject) => {
+                    httpServer!.close((err) => {
+                        if (err) reject(err)
+                        else resolve()
+                    })
+                })
+                httpServer = null
+            }
         },
 
         broadcast(name, data) {

packages/framework/server/src/helpers/define.ts

@@ -1,9 +1,9 @@
 /**
- * @zh API 和消息定义助手
- * @en API and message definition helpers
+ * @zh API、消息和 HTTP 定义助手
+ * @en API, message, and HTTP definition helpers
  */
 
-import type { ApiDefinition, MsgDefinition } from '../types/index.js'
+import type { ApiDefinition, MsgDefinition, HttpDefinition } from '../types/index.js'
 
 /**
  * @zh 定义 API 处理器
@@ -49,3 +49,33 @@ export function defineMsg<TMsg, TData = Record<string, unknown>>(
 ): MsgDefinition<TMsg, TData> {
     return definition
 }
+
+/**
+ * @zh 定义 HTTP 路由处理器
+ * @en Define HTTP route handler
+ *
+ * @example
+ * ```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
+ *         // ... validate credentials
+ *         res.json({ token: '...', userId: '...' })
+ *     }
+ * })
+ * ```
+ */
+export function defineHttp<TBody = unknown>(
+    definition: HttpDefinition<TBody>
+): HttpDefinition<TBody> {
+    return definition
+}

packages/framework/server/src/http/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @zh HTTP 模块导出
+ * @en HTTP module exports
+ */
+
+export * from './types.js';
+export { createHttpRouter } from './router.js';

packages/framework/server/src/http/router.ts

@@ -0,0 +1,263 @@
+/**
+ * @zh HTTP 路由器
+ * @en HTTP Router
+ *
+ * @zh 简洁的 HTTP 路由实现，支持与 WebSocket 共用端口
+ * @en Simple HTTP router implementation, supports sharing port with WebSocket
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type {
+    HttpRequest,
+    HttpResponse,
+    HttpHandler,
+    HttpRoutes,
+    CorsOptions,
+} from './types.js';
+
+/**
+ * @zh 创建 HTTP 请求对象
+ * @en Create HTTP request object
+ */
+async function createRequest(req: IncomingMessage): Promise<HttpRequest> {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+
+    // 解析查询参数
+    const query: Record<string, string> = {};
+    url.searchParams.forEach((value, key) => {
+        query[key] = value;
+    });
+
+    // 解析请求体
+    let body: unknown = null;
+    if (req.method === 'POST' || req.method === 'PUT' || req.method === 'PATCH') {
+        body = await parseBody(req);
+    }
+
+    // 获取客户端 IP
+    const ip =
+        (req.headers['x-forwarded-for'] as string)?.split(',')[0]?.trim() ||
+        req.socket?.remoteAddress ||
+        'unknown';
+
+    return {
+        raw: req,
+        method: req.method ?? 'GET',
+        path: url.pathname,
+        query,
+        headers: req.headers as Record<string, string | string[] | undefined>,
+        body,
+        ip,
+    };
+}
+
+/**
+ * @zh 解析请求体
+ * @en Parse request body
+ */
+function parseBody(req: IncomingMessage): Promise<unknown> {
+    return new Promise((resolve) => {
+        const chunks: Buffer[] = [];
+
+        req.on('data', (chunk: Buffer) => {
+            chunks.push(chunk);
+        });
+
+        req.on('end', () => {
+            const rawBody = Buffer.concat(chunks).toString('utf-8');
+
+            if (!rawBody) {
+                resolve(null);
+                return;
+            }
+
+            const contentType = req.headers['content-type'] ?? '';
+
+            if (contentType.includes('application/json')) {
+                try {
+                    resolve(JSON.parse(rawBody));
+                } catch {
+                    resolve(rawBody);
+                }
+            } else if (contentType.includes('application/x-www-form-urlencoded')) {
+                const params = new URLSearchParams(rawBody);
+                const result: Record<string, string> = {};
+                params.forEach((value, key) => {
+                    result[key] = value;
+                });
+                resolve(result);
+            } else {
+                resolve(rawBody);
+            }
+        });
+
+        req.on('error', () => {
+            resolve(null);
+        });
+    });
+}
+
+/**
+ * @zh 创建 HTTP 响应对象
+ * @en Create HTTP response object
+ */
+function createResponse(res: ServerResponse): HttpResponse {
+    let statusCode = 200;
+
+    const response: HttpResponse = {
+        raw: res,
+
+        status(code: number) {
+            statusCode = code;
+            return response;
+        },
+
+        header(name: string, value: string) {
+            res.setHeader(name, value);
+            return response;
+        },
+
+        json(data: unknown) {
+            res.setHeader('Content-Type', 'application/json; charset=utf-8');
+            res.statusCode = statusCode;
+            res.end(JSON.stringify(data));
+        },
+
+        text(data: string) {
+            res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+            res.statusCode = statusCode;
+            res.end(data);
+        },
+
+        error(code: number, message: string) {
+            res.setHeader('Content-Type', 'application/json; charset=utf-8');
+            res.statusCode = code;
+            res.end(JSON.stringify({ error: message }));
+        },
+    };
+
+    return response;
+}
+
+/**
+ * @zh 应用 CORS 头
+ * @en Apply CORS headers
+ */
+function applyCors(res: ServerResponse, req: IncomingMessage, cors: CorsOptions): void {
+    const origin = req.headers.origin;
+
+    // 处理 origin
+    if (cors.origin === true || cors.origin === '*') {
+        res.setHeader('Access-Control-Allow-Origin', origin ?? '*');
+    } else if (typeof cors.origin === 'string') {
+        res.setHeader('Access-Control-Allow-Origin', cors.origin);
+    } else if (Array.isArray(cors.origin) && origin && cors.origin.includes(origin)) {
+        res.setHeader('Access-Control-Allow-Origin', origin);
+    }
+
+    // 允许的方法
+    if (cors.methods) {
+        res.setHeader('Access-Control-Allow-Methods', cors.methods.join(', '));
+    } else {
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS');
+    }
+
+    // 允许的头
+    if (cors.allowedHeaders) {
+        res.setHeader('Access-Control-Allow-Headers', cors.allowedHeaders.join(', '));
+    } else {
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+    }
+
+    // 凭证
+    if (cors.credentials) {
+        res.setHeader('Access-Control-Allow-Credentials', 'true');
+    }
+
+    // 缓存
+    if (cors.maxAge) {
+        res.setHeader('Access-Control-Max-Age', String(cors.maxAge));
+    }
+}
+
+/**
+ * @zh 创建 HTTP 路由器
+ * @en Create HTTP router
+ */
+export function createHttpRouter(routes: HttpRoutes, cors?: CorsOptions | boolean) {
+    // 解析路由
+    const parsedRoutes: Array<{
+        method: string;
+        path: string;
+        handler: HttpHandler;
+    }> = [];
+
+    for (const [path, handlerOrMethods] of Object.entries(routes)) {
+        if (typeof handlerOrMethods === 'function') {
+            // 简单形式：路径 -> 处理器（接受所有方法）
+            parsedRoutes.push({ method: '*', path, handler: handlerOrMethods });
+        } else {
+            // 对象形式：路径 -> { GET, POST, ... }
+            for (const [method, handler] of Object.entries(handlerOrMethods)) {
+                if (handler !== undefined) {
+                    parsedRoutes.push({ method, path, handler });
+                }
+            }
+        }
+    }
+
+    // 默认 CORS 配置
+    const corsOptions: CorsOptions | null =
+        cors === true
+            ? { origin: true, credentials: true }
+            : cors === false
+                ? null
+                : cors ?? null;
+
+    /**
+     * @zh 处理 HTTP 请求
+     * @en Handle HTTP request
+     */
+    return async function handleRequest(
+        req: IncomingMessage,
+        res: ServerResponse
+    ): Promise<boolean> {
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        const path = url.pathname;
+        const method = req.method ?? 'GET';
+
+        // 应用 CORS
+        if (corsOptions) {
+            applyCors(res, req, corsOptions);
+
+            // 处理预检请求
+            if (method === 'OPTIONS') {
+                res.statusCode = 204;
+                res.end();
+                return true;
+            }
+        }
+
+        // 查找匹配的路由
+        const route = parsedRoutes.find(
+            (r) => r.path === path && (r.method === '*' || r.method === method)
+        );
+
+        if (!route) {
+            return false; // 未找到路由，让其他处理器处理
+        }
+
+        try {
+            const httpReq = await createRequest(req);
+            const httpRes = createResponse(res);
+            await route.handler(httpReq, httpRes);
+            return true;
+        } catch (error) {
+            console.error('[HTTP] Route handler error:', error);
+            res.statusCode = 500;
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify({ error: 'Internal Server Error' }));
+            return true;
+        }
+    };
+}

packages/framework/server/src/http/types.ts

@@ -0,0 +1,161 @@
+/**
+ * @zh HTTP 路由类型定义
+ * @en HTTP router type definitions
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+/**
+ * @zh HTTP 请求上下文
+ * @en HTTP request context
+ */
+export interface HttpRequest {
+    /**
+     * @zh 原始请求对象
+     * @en Raw request object
+     */
+    raw: IncomingMessage;
+
+    /**
+     * @zh 请求方法
+     * @en Request method
+     */
+    method: string;
+
+    /**
+     * @zh 请求路径
+     * @en Request path
+     */
+    path: string;
+
+    /**
+     * @zh 查询参数
+     * @en Query parameters
+     */
+    query: Record<string, string>;
+
+    /**
+     * @zh 请求头
+     * @en Request headers
+     */
+    headers: Record<string, string | string[] | undefined>;
+
+    /**
+     * @zh 解析后的 JSON 请求体
+     * @en Parsed JSON body
+     */
+    body: unknown;
+
+    /**
+     * @zh 客户端 IP
+     * @en Client IP
+     */
+    ip: string;
+}
+
+/**
+ * @zh HTTP 响应工具
+ * @en HTTP response utilities
+ */
+export interface HttpResponse {
+    /**
+     * @zh 原始响应对象
+     * @en Raw response object
+     */
+    raw: ServerResponse;
+
+    /**
+     * @zh 设置状态码
+     * @en Set status code
+     */
+    status(code: number): HttpResponse;
+
+    /**
+     * @zh 设置响应头
+     * @en Set response header
+     */
+    header(name: string, value: string): HttpResponse;
+
+    /**
+     * @zh 发送 JSON 响应
+     * @en Send JSON response
+     */
+    json(data: unknown): void;
+
+    /**
+     * @zh 发送文本响应
+     * @en Send text response
+     */
+    text(data: string): void;
+
+    /**
+     * @zh 发送错误响应
+     * @en Send error response
+     */
+    error(code: number, message: string): void;
+}
+
+/**
+ * @zh HTTP 路由处理器
+ * @en HTTP route handler
+ */
+export type HttpHandler = (req: HttpRequest, res: HttpResponse) => void | Promise<void>;
+
+/**
+ * @zh HTTP 路由定义
+ * @en HTTP route definition
+ */
+export interface HttpRoute {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | '*';
+    path: string;
+    handler: HttpHandler;
+}
+
+/**
+ * @zh HTTP 路由配置
+ * @en HTTP routes configuration
+ */
+export type HttpRoutes = Record<string, HttpHandler | {
+    GET?: HttpHandler;
+    POST?: HttpHandler;
+    PUT?: HttpHandler;
+    DELETE?: HttpHandler;
+    PATCH?: HttpHandler;
+    OPTIONS?: HttpHandler;
+}>;
+
+/**
+ * @zh CORS 配置
+ * @en CORS configuration
+ */
+export interface CorsOptions {
+    /**
+     * @zh 允许的来源
+     * @en Allowed origins
+     */
+    origin?: string | string[] | boolean;
+
+    /**
+     * @zh 允许的方法
+     * @en Allowed methods
+     */
+    methods?: string[];
+
+    /**
+     * @zh 允许的请求头
+     * @en Allowed headers
+     */
+    allowedHeaders?: string[];
+
+    /**
+     * @zh 是否允许携带凭证
+     * @en Allow credentials
+     */
+    credentials?: boolean;
+
+    /**
+     * @zh 预检请求缓存时间（秒）
+     * @en Preflight cache max age
+     */
+    maxAge?: number;
+}

packages/framework/server/src/index.ts

@@ -30,7 +30,7 @@
 export { createServer } from './core/server.js'
 
 // Helpers
-export { defineApi, defineMsg } from './helpers/define.js'
+export { defineApi, defineMsg, defineHttp } from './helpers/define.js'
 
 // Room System
 export { Room, type RoomOptions } from './room/Room.js'
@@ -46,7 +46,19 @@ export type {
     MsgContext,
     ApiDefinition,
     MsgDefinition,
+    HttpDefinition,
+    HttpMethod,
 } from './types/index.js'
 
+// HTTP
+export { createHttpRouter } from './http/router.js'
+export type {
+    HttpRequest,
+    HttpResponse,
+    HttpHandler,
+    HttpRoutes,
+    CorsOptions,
+} from './http/types.js'
+
 // Re-export useful types from @esengine/rpc
 export { RpcError, ErrorCode } from '@esengine/rpc'

packages/framework/server/src/router/loader.ts

@@ -6,7 +6,15 @@
 import * as fs from 'node:fs'
 import * as path from 'node:path'
 import { pathToFileURL } from 'node:url'
-import type { ApiDefinition, MsgDefinition, LoadedApiHandler, LoadedMsgHandler } from '../types/index.js'
+import type {
+    ApiDefinition,
+    MsgDefinition,
+    HttpDefinition,
+    LoadedApiHandler,
+    LoadedMsgHandler,
+    LoadedHttpHandler,
+    HttpMethod,
+} from '../types/index.js'
 
 /**
  * @zh 将文件名转换为 API/消息名称
@@ -110,3 +118,106 @@ export async function loadMsgHandlers(msgDir: string): Promise<LoadedMsgHandler[
 
     return handlers
 }
+
+/**
+ * @zh 递归扫描目录获取所有处理器文件
+ * @en Recursively scan directory for all handler files
+ */
+function scanDirectoryRecursive(dir: string, baseDir: string = dir): Array<{ filePath: string; relativePath: string }> {
+    if (!fs.existsSync(dir)) {
+        return []
+    }
+
+    const files: Array<{ filePath: string; relativePath: string }> = []
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name)
+
+        if (entry.isDirectory()) {
+            files.push(...scanDirectoryRecursive(fullPath, baseDir))
+        } else if (entry.isFile() && /\.(ts|js|mts|mjs)$/.test(entry.name)) {
+            if (entry.name.startsWith('_') || entry.name.startsWith('index.')) {
+                continue
+            }
+            const relativePath = path.relative(baseDir, fullPath)
+            files.push({ filePath: fullPath, relativePath })
+        }
+    }
+
+    return files
+}
+
+/**
+ * @zh 将文件路径转换为路由路径
+ * @en Convert file path to route path
+ *
+ * @example
+ * 'login.ts' -> '/login'
+ * 'users/profile.ts' -> '/users/profile'
+ * 'users/[id].ts' -> '/users/:id'
+ */
+function filePathToRoute(relativePath: string, prefix: string): string {
+    let route = relativePath
+        .replace(/\.(ts|js|mts|mjs)$/, '')
+        .replace(/\\/g, '/')
+        .replace(/\[([^\]]+)\]/g, ':$1')
+
+    if (!route.startsWith('/')) {
+        route = '/' + route
+    }
+
+    const fullRoute = prefix.endsWith('/')
+        ? prefix.slice(0, -1) + route
+        : prefix + route
+
+    return fullRoute
+}
+
+/**
+ * @zh 加载 HTTP 路由处理器
+ * @en Load HTTP route handlers
+ *
+ * @example
+ * ```typescript
+ * // Directory structure:
+ * // src/http/
+ * //   login.ts      -> POST /api/login
+ * //   register.ts   -> POST /api/register
+ * //   users/
+ * //     [id].ts     -> GET /api/users/:id
+ *
+ * const handlers = await loadHttpHandlers('src/http', '/api')
+ * ```
+ */
+export async function loadHttpHandlers(
+    httpDir: string,
+    prefix: string = '/api'
+): Promise<LoadedHttpHandler[]> {
+    const files = scanDirectoryRecursive(httpDir)
+    const handlers: LoadedHttpHandler[] = []
+
+    for (const { filePath, relativePath } of files) {
+        try {
+            const fileUrl = pathToFileURL(filePath).href
+            const module = await import(fileUrl)
+            const definition = module.default as HttpDefinition<unknown>
+
+            if (definition && typeof definition.handler === 'function') {
+                const route = filePathToRoute(relativePath, prefix)
+                const method: HttpMethod = definition.method ?? 'POST'
+
+                handlers.push({
+                    route,
+                    method,
+                    path: filePath,
+                    definition,
+                })
+            }
+        } catch (err) {
+            console.warn(`[Server] Failed to load HTTP handler: ${filePath}`, err)
+        }
+    }
+
+    return handlers
+}

packages/framework/server/src/types/index.ts

@@ -4,6 +4,7 @@
  */
 
 import type { Connection, ProtocolDef } from '@esengine/rpc'
+import type { HttpRoutes, CorsOptions, HttpRequest, HttpResponse } from '../http/types.js'
 
 // ============================================================================
 // Server Config
@@ -35,6 +36,29 @@ export interface ServerConfig {
      */
     msgDir?: string
 
+    /**
+     * @zh HTTP 路由目录路径
+     * @en HTTP routes directory path
+     * @default 'src/http'
+     *
+     * @zh 文件命名规则：
+     * - `login.ts` → POST /api/login
+     * - `users/[id].ts` → /api/users/:id
+     * - `health.ts` (method: 'GET') → GET /api/health
+     * @en File naming convention:
+     * - `login.ts` → POST /api/login
+     * - `users/[id].ts` → /api/users/:id
+     * - `health.ts` (method: 'GET') → GET /api/health
+     */
+    httpDir?: string
+
+    /**
+     * @zh HTTP 路由前缀
+     * @en HTTP routes prefix
+     * @default '/api'
+     */
+    httpPrefix?: string
+
     /**
      * @zh 游戏 Tick 速率 (每秒)
      * @en Game tick rate (per second)
@@ -42,6 +66,19 @@ export interface ServerConfig {
      */
     tickRate?: number
 
+    /**
+     * @zh HTTP 路由配置（内联定义，与 httpDir 文件路由合并）
+     * @en HTTP routes configuration (inline definition, merged with httpDir file routes)
+     */
+    http?: HttpRoutes
+
+    /**
+     * @zh CORS 配置
+     * @en CORS configuration
+     * @default true
+     */
+    cors?: CorsOptions | boolean
+
     /**
      * @zh 服务器启动回调
      * @en Server start callback
@@ -232,3 +269,80 @@ export interface LoadedMsgHandler {
     path: string
     definition: MsgDefinition<any, any>
 }
+
+// ============================================================================
+// HTTP Definition
+// ============================================================================
+
+/**
+ * @zh HTTP 请求方法
+ * @en HTTP request method
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
+
+/**
+ * @zh HTTP 定义选项
+ * @en HTTP definition options
+ *
+ * @example
+ * ```typescript
+ * // src/http/login.ts
+ * import { defineHttp } from '@esengine/server'
+ *
+ * export default defineHttp({
+ *     method: 'POST',
+ *     handler: async (req, res) => {
+ *         const { username, password } = req.body
+ *         // ... authentication logic
+ *         res.json({ token: '...', userId: '...' })
+ *     }
+ * })
+ * ```
+ */
+export interface HttpDefinition<TBody = unknown> {
+    /**
+     * @zh 请求方法
+     * @en Request method
+     * @default 'POST'
+     */
+    method?: HttpMethod
+
+    /**
+     * @zh 处理函数
+     * @en Handler function
+     */
+    handler: (
+        req: HttpRequest & { body: TBody },
+        res: HttpResponse
+    ) => void | Promise<void>
+}
+
+/**
+ * @zh 已加载的 HTTP 处理器
+ * @en Loaded HTTP handler
+ */
+export interface LoadedHttpHandler {
+    /**
+     * @zh 路由路径（如 /api/login）
+     * @en Route path (e.g., /api/login)
+     */
+    route: string
+
+    /**
+     * @zh 请求方法
+     * @en Request method
+     */
+    method: HttpMethod
+
+    /**
+     * @zh 源文件路径
+     * @en Source file path
+     */
+    path: string
+
+    /**
+     * @zh 处理器定义
+     * @en Handler definition
+     */
+    definition: HttpDefinition<any>
+}

packages/framework/transaction/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @esengine/transaction
 
+## 2.0.7
+
+### Patch Changes
+
+- Updated dependencies [[`902c0a1`](https://github.com/esengine/esengine/commit/902c0a10749f80bd8f499b44154646379d359704)]:
+    - @esengine/server@4.2.0
+
+## 2.0.6
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/server@4.1.0
+
 ## 2.0.5
 
 ### Patch Changes

packages/framework/transaction/package.json

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

packages/physics/rapier2d/scripts/gen-src.mjs

@@ -14,7 +14,7 @@ import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, '..');
-const rapierRoot = join(packageRoot, '..', '..', 'thirdparty', 'rapier.js');
+const rapierRoot = join(packageRoot, '..', '..', '..', 'thirdparty', 'rapier.js');
 const srcTsDir = join(rapierRoot, 'src.ts');
 const src2dDir = join(rapierRoot, 'rapier-compat', 'src2d');
 const outputDir = join(packageRoot, 'src');

packages/physics/rapier2d/src/init.ts

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

packages/physics/rapier2d/tsup.config.ts

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

scripts/build-rapier2d.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+/**
+ * Build Rapier2D WASM artifacts
+ * 构建 Rapier2D WASM 产物
+ *
+ * This script automates the entire Rapier2D WASM build process:
+ * 此脚本自动化整个 Rapier2D WASM 构建流程：
+ *
+ * 1. Prepare Rust project from thirdparty/rapier.js
+ * 2. Build WASM using wasm-pack
+ * 3. Copy artifacts to packages/physics/rapier2d/pkg
+ * 4. Generate TypeScript source code
+ */
+
+import { execSync, spawn } from 'child_process';
+import { existsSync, cpSync, rmSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = join(__dirname, '..');
+const rapierJsDir = join(rootDir, 'thirdparty', 'rapier.js');
+const rapier2dBuildDir = join(rapierJsDir, 'builds', 'rapier2d');
+const rapier2dPkgSrc = join(rapier2dBuildDir, 'pkg');
+const rapier2dPkgDest = join(rootDir, 'packages', 'physics', 'rapier2d', 'pkg');
+
+/**
+ * Run a command and stream output
+ */
+function runCommand(command, cwd, description) {
+    console.log(`\n📦 ${description}...`);
+    console.log(`   Running: ${command}`);
+    console.log(`   In: ${cwd}\n`);
+
+    try {
+        execSync(command, {
+            cwd,
+            stdio: 'inherit',
+            shell: true
+        });
+        return true;
+    } catch (error) {
+        console.error(`❌ Failed: ${description}`);
+        return false;
+    }
+}
+
+/**
+ * Main build function
+ */
+async function build() {
+    console.log('🚀 Building Rapier2D WASM...\n');
+
+    // Check if rapier.js exists
+    if (!existsSync(rapierJsDir)) {
+        console.error('❌ Error: thirdparty/rapier.js not found!');
+        console.error('   Please clone it first:');
+        console.error('   git clone https://github.com/esengine/rapier.js.git thirdparty/rapier.js');
+        process.exit(1);
+    }
+
+    // Check if Rust/Cargo is installed
+    try {
+        execSync('cargo --version', { stdio: 'pipe' });
+    } catch {
+        console.error('❌ Error: Rust/Cargo not found!');
+        console.error('   Please install Rust: https://rustup.rs/');
+        process.exit(1);
+    }
+
+    // Check if wasm-pack is installed
+    try {
+        execSync('wasm-pack --version', { stdio: 'pipe' });
+    } catch {
+        console.error('❌ Error: wasm-pack not found!');
+        console.error('   Please install it: cargo install wasm-pack');
+        process.exit(1);
+    }
+
+    // Step 1: Prepare Rust project
+    if (!runCommand(
+        'cargo run -p prepare_builds -- -d dim2 -f non-deterministic',
+        rapierJsDir,
+        'Step 1/4: Preparing Rust project'
+    )) {
+        process.exit(1);
+    }
+
+    // Step 2: Install npm dependencies for rapier2d build
+    if (!runCommand(
+        'npm install',
+        rapier2dBuildDir,
+        'Step 2/4: Installing npm dependencies'
+    )) {
+        process.exit(1);
+    }
+
+    // Step 3: Build WASM
+    if (!runCommand(
+        'npm run build',
+        rapier2dBuildDir,
+        'Step 3/4: Building WASM'
+    )) {
+        process.exit(1);
+    }
+
+    // Step 4: Copy pkg to packages/physics/rapier2d/pkg
+    console.log('\n📦 Step 4/4: Copying WASM artifacts...');
+    console.log(`   From: ${rapier2dPkgSrc}`);
+    console.log(`   To: ${rapier2dPkgDest}\n`);
+
+    if (!existsSync(rapier2dPkgSrc)) {
+        console.error('❌ Error: Build output not found at', rapier2dPkgSrc);
+        process.exit(1);
+    }
+
+    // Remove old pkg if exists
+    if (existsSync(rapier2dPkgDest)) {
+        rmSync(rapier2dPkgDest, { recursive: true });
+    }
+
+    // Copy new pkg
+    cpSync(rapier2dPkgSrc, rapier2dPkgDest, { recursive: true });
+    console.log('   ✅ Copied successfully!\n');
+
+    // Step 5: Generate TypeScript source
+    if (!runCommand(
+        'pnpm --filter @esengine/rapier2d gen:src',
+        rootDir,
+        'Bonus: Generating TypeScript source'
+    )) {
+        console.warn('⚠️  Warning: Failed to generate TypeScript source.');
+        console.warn('   You can run it manually: pnpm --filter @esengine/rapier2d gen:src');
+    }
+
+    console.log('\n✅ Rapier2D WASM build completed successfully!');
+    console.log('\nNext steps:');
+    console.log('  1. Run: pnpm build:editor');
+    console.log('  2. Start editor: cd packages/editor/editor-app && pnpm tauri:dev\n');
+}
+
+build().catch(error => {
+    console.error('❌ Build failed:', error);
+    process.exit(1);
+});