esengine/packages/framework/server/CHANGELOG.md

@esengine/server

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:

  // 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:

  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

• Updated dependencies [1f3a76a]:
  • @esengine/ecs-framework@2.7.0

3.0.0

Minor Changes

• feat(ecs): 添加 @NetworkEntity 装饰器，支持自动广播实体生成/销毁

  新功能

  @NetworkEntity 装饰器

  • 标记组件为网络实体，自动广播 spawn/despawn 消息
  • 支持 autoSpawn 和 autoDespawn 配置选项
  • 通过事件系统（ECSEventType.COMPONENT_ADDED / ECSEventType.ENTITY_DESTROYED）实现

  ECSRoom 增强

  • 新增 enableAutoNetworkEntity 配置选项（默认启用）
  • 自动监听组件添加和实体销毁事件
  • 简化 GameRoom 实现，无需手动回调

  改进

  Entity 事件

  • Entity.destroy() 现在发出 entity:destroyed 事件
  • Entity.active 变化时发出 entity:enabled / entity:disabled 事件
  • 使用 ECSEventType 常量替代硬编码字符串

  使用示例

  import { Component, ECSComponent, sync, NetworkEntity } from '@esengine/ecs-framework';
  
  @ECSComponent('Enemy')
  @NetworkEntity('Enemy')
  class EnemyComponent extends Component {
      @sync('float32') x: number = 0;
      @sync('float32') y: number = 0;
  }
  
  // 服务端
  const entity = scene.createEntity('Enemy');
  entity.addComponent(new EnemyComponent()); // 自动广播 spawn
  entity.destroy(); // 自动广播 despawn
  

Patch Changes

• Updated dependencies []:
  • @esengine/ecs-framework@2.6.0

2.0.0

Minor Changes

• #390 1f297ac Thanks @esengine! - feat: ECS 网络状态同步系统

  @esengine/ecs-framework

  新增 @sync 装饰器和二进制编解码器，支持基于 Component 的网络状态同步：

  import { Component, ECSComponent, sync } from '@esengine/ecs-framework';
  
  @ECSComponent('Player')
  class PlayerComponent extends Component {
      @sync('string') name: string = '';
      @sync('uint16') score: number = 0;
      @sync('float32') x: number = 0;
      @sync('float32') y: number = 0;
  }
  

  新增导出

  • sync - 标记需要同步的字段装饰器
  • SyncType - 支持的同步类型
  • SyncOperation - 同步操作类型（FULL/DELTA/SPAWN/DESPAWN）
  • encodeSnapshot / decodeSnapshot - 批量编解码
  • encodeSpawn / decodeSpawn - 实体生成编解码
  • encodeDespawn / processDespawn - 实体销毁编解码
  • ChangeTracker - 字段级变更追踪
  • initChangeTracker / clearChanges / hasChanges - 变更追踪工具函数

  内部方法标记

  将以下方法标记为 @internal，用户应通过 Core.update() 驱动更新：

  • Scene.update()
  • SceneManager.update()
  • WorldManager.updateAll()

  @esengine/network

  新增 ComponentSyncSystem，基于 @sync 装饰器自动同步组件状态：

  import { ComponentSyncSystem } from '@esengine/network';
  
  // 服务端：编码状态
  const data = syncSystem.encodeAllEntities(false);
  
  // 客户端：解码状态
  syncSystem.applySnapshot(data);
  

  修复

  • 将 @esengine/ecs-framework 从 devDependencies 移到 peerDependencies

  @esengine/server

  新增 ECSRoom，带有 ECS World 支持的房间基类：

  import { ECSRoom } from '@esengine/server/ecs';
  
  // 服务端启动
  Core.create();
  setInterval(() => Core.update(1 / 60), 16);
  
  // 定义房间
  class GameRoom extends ECSRoom {
      onCreate() {
          this.addSystem(new PhysicsSystem());
      }
  
      onJoin(player: Player) {
          const entity = this.createPlayerEntity(player.id);
          entity.addComponent(new PlayerComponent());
      }
  }
  

  设计

  • 每个 ECSRoom 在 Core.worldManager 中创建独立的 World
  • Core.update() 统一更新 Time 和所有 World
  • onTick() 只处理状态同步逻辑

Patch Changes

• Updated dependencies [1f297ac]:
  • @esengine/ecs-framework@2.5.0

1.3.0

Minor Changes

• #388 afdeb00 Thanks @esengine! - feat(server): 添加可插拔速率限制系统 | add pluggable rate limiting system
  • 新增令牌桶策略 (TokenBucketStrategy) - 推荐用于一般场景
  • 新增滑动窗口策略 (SlidingWindowStrategy) - 精确跟踪
  • 新增固定窗口策略 (FixedWindowStrategy) - 简单高效
  • 新增房间速率限制 mixin (withRateLimit)
  • 新增速率限制装饰器 (@rateLimit, @noRateLimit)
  • 新增按消息类型限流装饰器 (@rateLimitMessage, @noRateLimitMessage)
  • 支持与认证系统组合使用
  • 导出路径: @esengine/server/ratelimit

1.2.0

Minor Changes

• #386 61a13ba Thanks @esengine! - feat(server): 添加可插拔认证系统 | add pluggable authentication system
  • 新增 JWT 认证提供者 (createJwtAuthProvider)
  • 新增 Session 认证提供者 (createSessionAuthProvider)
  • 新增服务器认证 mixin (withAuth)
  • 新增房间认证 mixin (withRoomAuth)
  • 新增认证装饰器 (@requireAuth, @requireRole)
  • 新增测试工具 (MockAuthProvider)
  • 导出路径: @esengine/server/auth, @esengine/server/auth/testing

1.1.4

Patch Changes

• Updated dependencies [a000cc0]:
  • @esengine/rpc@1.1.1

1.1.3

Patch Changes

• #372 9c41181 Thanks @esengine! - fix: expose id property on ServerConnection type

  TypeScript was not properly resolving the inherited id property from the base Connection interface in some module resolution scenarios. This fix explicitly declares the id property on ServerConnection to ensure it's always visible to consumers.

1.1.2

Patch Changes

• #370 18df9d1 Thanks @esengine! - fix: allow define() to be called before start()

  Previously, calling server.define() before server.start() would throw an error because roomManager was initialized inside start(). This fix moves the roomManager initialization to createServer(), allowing the expected usage pattern:

  const server = await createServer({ port: 3000 });
  server.define('world', WorldRoom); // Now works correctly
  await server.start();
  

1.1.1

Patch Changes

• #368 66d5dc2 Thanks @esengine! - fix: 修复发布缺少 dist 目录 | fix missing dist in published packages

1.1.0

Minor Changes

• #366 b6f1235 Thanks @esengine! - feat(server): 添加游戏服务器框架与房间系统 | add game server framework with Room system

  @esengine/server - 游戏服务器框架 | Game server framework

  • 文件路由系统 | File-based routing
  • Room 生命周期管理 (onCreate, onJoin, onLeave, onTick, onDispose) | Room lifecycle management
  • @onMessage 装饰器处理消息 | Message handler decorator
  • 玩家管理与断线处理 | Player management with auto-disconnect
  • 内置 JoinRoom/LeaveRoom API | Built-in room APIs
  • defineApi/defineMsg 类型安全辅助函数 | Type-safe helper functions

  create-esengine-server - CLI 脚手架工具 | CLI scaffolding tool

  • 生成 shared/server/client 项目结构 | Creates project structure
  • 类型安全的协议定义 | Type-safe protocol definitions
  • 包含 GameRoom 示例实现 | Includes example implementation