@esengine/server 1.2.0 → 2.0.0

package/dist/ecs/index.js

@@ -0,0 +1,247 @@
+import { Room } from '../chunk-O3VN2QVN.js';
+export { onMessage } from '../chunk-O3VN2QVN.js';
+import { __name, __publicField } from '../chunk-T626JPC7.js';
+import { Core, encodeDespawn, encodeSnapshot, SyncOperation, encodeSpawn, SYNC_METADATA, CHANGE_TRACKER, initChangeTracker } from '@esengine/ecs-framework';
+export { SyncOperation, clearChanges, getSyncMetadata, hasChanges, hasSyncFields, initChangeTracker, sync } from '@esengine/ecs-framework';
+
+var DEFAULT_ECS_CONFIG = {
+  syncInterval: 50,
+  enableDeltaSync: true
+};
+var NETWORK_ENTITY_OWNER = /* @__PURE__ */ Symbol("NetworkEntityOwner");
+var _ECSRoom = class _ECSRoom extends Room {
+  constructor(ecsConfig) {
+    super();
+    /**
+     * @zh ECS World（由 Core.worldManager 管理）
+     * @en ECS World (managed by Core.worldManager)
+     */
+    __publicField(this, "world");
+    /**
+     * @zh World 在 WorldManager 中的 ID
+     * @en World ID in WorldManager
+     */
+    __publicField(this, "worldId");
+    /**
+     * @zh 房间的主场景
+     * @en Room's main scene
+     */
+    __publicField(this, "scene");
+    /**
+     * @zh ECS 配置
+     * @en ECS configuration
+     */
+    __publicField(this, "ecsConfig");
+    /**
+     * @zh 玩家 ID 到实体的映射
+     * @en Player ID to Entity mapping
+     */
+    __publicField(this, "_playerEntities", /* @__PURE__ */ new Map());
+    /**
+     * @zh 上次同步时间
+     * @en Last sync time
+     */
+    __publicField(this, "_lastSyncTime", 0);
+    this.ecsConfig = {
+      ...DEFAULT_ECS_CONFIG,
+      ...ecsConfig
+    };
+    this.worldId = `room_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    this.world = Core.worldManager.createWorld(this.worldId);
+    this.scene = this.world.createScene("game");
+    this.world.setSceneActive("game", true);
+    this.world.start();
+  }
+  // =========================================================================
+  // Scene Management | 场景管理
+  // =========================================================================
+  /**
+   * @zh 添加系统到场景
+   * @en Add system to scene
+   */
+  addSystem(system) {
+    this.scene.addSystem(system);
+  }
+  /**
+   * @zh 创建实体
+   * @en Create entity
+   */
+  createEntity(name) {
+    return this.scene.createEntity(name ?? `entity_${Date.now()}`);
+  }
+  /**
+   * @zh 为玩家创建实体
+   * @en Create entity for player
+   *
+   * @param playerId - @zh 玩家 ID @en Player ID
+   * @param name - @zh 实体名称 @en Entity name
+   * @returns @zh 创建的实体 @en Created entity
+   */
+  createPlayerEntity(playerId, name) {
+    const entityName = name ?? `player_${playerId}`;
+    const entity = this.scene.createEntity(entityName);
+    entity[NETWORK_ENTITY_OWNER] = playerId;
+    this._playerEntities.set(playerId, entity);
+    return entity;
+  }
+  /**
+   * @zh 获取玩家的实体
+   * @en Get player's entity
+   */
+  getPlayerEntity(playerId) {
+    return this._playerEntities.get(playerId);
+  }
+  /**
+   * @zh 销毁玩家的实体
+   * @en Destroy player's entity
+   */
+  destroyPlayerEntity(playerId) {
+    const entity = this._playerEntities.get(playerId);
+    if (entity) {
+      const despawnData = encodeDespawn(entity.id);
+      this.broadcastBinary(despawnData);
+      entity.destroy();
+      this._playerEntities.delete(playerId);
+    }
+  }
+  // =========================================================================
+  // State Sync | 状态同步
+  // =========================================================================
+  /**
+   * @zh 广播二进制数据
+   * @en Broadcast binary data
+   */
+  broadcastBinary(data) {
+    for (const player of this.players) {
+      this.sendBinary(player, data);
+    }
+  }
+  /**
+   * @zh 发送二进制数据给指定玩家
+   * @en Send binary data to specific player
+   */
+  sendBinary(player, data) {
+    player.send("$sync", {
+      data: Array.from(data)
+    });
+  }
+  /**
+   * @zh 发送完整状态给玩家（用于玩家刚加入时）
+   * @en Send full state to player (for when player just joined)
+   */
+  sendFullState(player) {
+    const entities = this._getSyncEntities();
+    if (entities.length === 0) return;
+    for (const entity of entities) {
+      this._initComponentTrackers(entity);
+    }
+    const data = encodeSnapshot(entities, SyncOperation.FULL);
+    this.sendBinary(player, data);
+  }
+  /**
+   * @zh 广播实体生成
+   * @en Broadcast entity spawn
+   */
+  broadcastSpawn(entity, prefabType) {
+    this._initComponentTrackers(entity);
+    const data = encodeSpawn(entity, prefabType);
+    this.broadcastBinary(data);
+  }
+  /**
+   * @zh 广播增量状态更新
+   * @en Broadcast delta state update
+   */
+  broadcastDelta() {
+    const entities = this._getSyncEntities();
+    const changedEntities = entities.filter((entity) => this._hasChanges(entity));
+    if (changedEntities.length === 0) return;
+    const data = encodeSnapshot(changedEntities, SyncOperation.DELTA);
+    this.broadcastBinary(data);
+    this._clearChangeTrackers(changedEntities);
+  }
+  // =========================================================================
+  // Lifecycle Overrides | 生命周期重载
+  // =========================================================================
+  /**
+   * @zh 游戏循环，处理状态同步
+   * @en Game tick, handles state sync
+   */
+  onTick(_dt) {
+    if (this.ecsConfig.enableDeltaSync) {
+      const now = Date.now();
+      if (now - this._lastSyncTime >= this.ecsConfig.syncInterval) {
+        this._lastSyncTime = now;
+        this.broadcastDelta();
+      }
+    }
+  }
+  /**
+   * @zh 玩家离开时自动销毁其实体
+   * @en Auto destroy player entity when leaving
+   */
+  async onLeave(player, reason) {
+    this.destroyPlayerEntity(player.id);
+  }
+  /**
+   * @zh 房间销毁时从 WorldManager 移除 World
+   * @en Remove World from WorldManager when room is disposed
+   */
+  onDispose() {
+    this._playerEntities.clear();
+    Core.worldManager.removeWorld(this.worldId);
+  }
+  // =========================================================================
+  // Internal | 内部方法
+  // =========================================================================
+  _getSyncEntities() {
+    const entities = [];
+    for (const entity of this.scene.entities.buffer) {
+      if (this._hasSyncComponents(entity)) {
+        entities.push(entity);
+      }
+    }
+    return entities;
+  }
+  _hasSyncComponents(entity) {
+    for (const component of entity.components) {
+      const metadata = component.constructor[SYNC_METADATA];
+      if (metadata && metadata.fields.length > 0) {
+        return true;
+      }
+    }
+    return false;
+  }
+  _hasChanges(entity) {
+    for (const component of entity.components) {
+      const tracker = component[CHANGE_TRACKER];
+      if (tracker?.hasChanges()) {
+        return true;
+      }
+    }
+    return false;
+  }
+  _initComponentTrackers(entity) {
+    for (const component of entity.components) {
+      const metadata = component.constructor[SYNC_METADATA];
+      if (metadata && metadata.fields.length > 0) {
+        initChangeTracker(component);
+      }
+    }
+  }
+  _clearChangeTrackers(entities) {
+    for (const entity of entities) {
+      for (const component of entity.components) {
+        const tracker = component[CHANGE_TRACKER];
+        if (tracker) {
+          tracker.clear();
+        }
+      }
+    }
+  }
+};
+__name(_ECSRoom, "ECSRoom");
+var ECSRoom = _ECSRoom;
+
+export { ECSRoom };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/ecs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ecs/ECSRoom.ts"],"names":["DEFAULT_ECS_CONFIG","syncInterval","enableDeltaSync","NETWORK_ENTITY_OWNER","ECSRoom","Room","ecsConfig","world","worldId","scene","_playerEntities","Map","_lastSyncTime","Date","now","Math","random","toString","slice","Core","worldManager","createWorld","createScene","setSceneActive","start","addSystem","system","createEntity","name","createPlayerEntity","playerId","entityName","entity","set","getPlayerEntity","get","destroyPlayerEntity","despawnData","encodeDespawn","id","broadcastBinary","destroy","delete","data","player","players","sendBinary","send","Array","from","sendFullState","entities","_getSyncEntities","length","_initComponentTrackers","encodeSnapshot","SyncOperation","FULL","broadcastSpawn","prefabType","encodeSpawn","broadcastDelta","changedEntities","filter","_hasChanges","DELTA","_clearChangeTrackers","onTick","_dt","onLeave","reason","onDispose","clear","removeWorld","buffer","_hasSyncComponents","push","component","components","metadata","SYNC_METADATA","fields","tracker","CHANGE_TRACKER","hasChanges","initChangeTracker"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @zh ECS 房间基类\n * @en ECS Room base class\n */\n\nimport {\n    Core,\n    Scene,\n    World,\n    Entity,\n    EntitySystem,\n    type Component,\n    // Sync\n    SyncOperation,\n    SYNC_METADATA,\n    CHANGE_TRACKER,\n    type SyncMetadata,\n    type ChangeTracker,\n    encodeSnapshot,\n    encodeSpawn,\n    encodeDespawn,\n    initChangeTracker,\n} from '@esengine/ecs-framework';\n\nimport { Room, type RoomOptions } from '../room/Room.js';\nimport type { Player } from '../room/Player.js';\n\n// =============================================================================\n// Types | 类型定义\n// =============================================================================\n\n/**\n * @zh ECS 房间配置\n * @en ECS room configuration\n */\nexport interface ECSRoomConfig {\n    /**\n     * @zh 状态同步间隔（毫秒）\n     * @en State sync interval in milliseconds\n     */\n    syncInterval: number;\n\n    /**\n     * @zh 是否启用增量同步\n     * @en Whether to enable delta sync\n     */\n    enableDeltaSync: boolean;\n}\n\nconst DEFAULT_ECS_CONFIG: ECSRoomConfig = {\n    syncInterval: 50, // 20 Hz\n    enableDeltaSync: true,\n};\n\n/**\n * @zh 网络实体标识组件\n * @en Network entity identity component\n */\nconst NETWORK_ENTITY_OWNER = Symbol('NetworkEntityOwner');\n\n// =============================================================================\n// ECSRoom | ECS 房间\n// =============================================================================\n\n/**\n * @zh ECS 房间基类，带有 ECS World 支持和自动状态同步\n * @en ECS Room base class with ECS World support and automatic state synchronization\n *\n * @example\n * ```typescript\n * // 服务端启动\n * Core.create();\n * setInterval(() => Core.update(1/60), 16);\n *\n * // 定义房间\n * class GameRoom extends ECSRoom {\n *     onCreate() {\n *         this.addSystem(new PhysicsSystem());\n *     }\n *\n *     onJoin(player: Player) {\n *         const entity = this.createPlayerEntity(player.id);\n *         entity.addComponent(new PlayerComponent());\n *     }\n * }\n * ```\n */\nexport abstract class ECSRoom<TState = any, TPlayerData = Record<string, unknown>> extends Room<TState, TPlayerData> {\n    /**\n     * @zh ECS World（由 Core.worldManager 管理）\n     * @en ECS World (managed by Core.worldManager)\n     */\n    protected readonly world: World;\n\n    /**\n     * @zh World 在 WorldManager 中的 ID\n     * @en World ID in WorldManager\n     */\n    protected readonly worldId: string;\n\n    /**\n     * @zh 房间的主场景\n     * @en Room's main scene\n     */\n    protected readonly scene: Scene;\n\n    /**\n     * @zh ECS 配置\n     * @en ECS configuration\n     */\n    protected readonly ecsConfig: ECSRoomConfig;\n\n    /**\n     * @zh 玩家 ID 到实体的映射\n     * @en Player ID to Entity mapping\n     */\n    private readonly _playerEntities: Map<string, Entity> = new Map();\n\n    /**\n     * @zh 上次同步时间\n     * @en Last sync time\n     */\n    private _lastSyncTime: number = 0;\n\n    constructor(ecsConfig?: Partial<ECSRoomConfig>) {\n        super();\n        this.ecsConfig = { ...DEFAULT_ECS_CONFIG, ...ecsConfig };\n\n        this.worldId = `room_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;\n        this.world = Core.worldManager.createWorld(this.worldId);\n        this.scene = this.world.createScene('game');\n        this.world.setSceneActive('game', true);\n        this.world.start();\n    }\n\n    // =========================================================================\n    // Scene Management | 场景管理\n    // =========================================================================\n\n    /**\n     * @zh 添加系统到场景\n     * @en Add system to scene\n     */\n    protected addSystem(system: EntitySystem): void {\n        this.scene.addSystem(system);\n    }\n\n    /**\n     * @zh 创建实体\n     * @en Create entity\n     */\n    protected createEntity(name?: string): Entity {\n        return this.scene.createEntity(name ?? `entity_${Date.now()}`);\n    }\n\n    /**\n     * @zh 为玩家创建实体\n     * @en Create entity for player\n     *\n     * @param playerId - @zh 玩家 ID @en Player ID\n     * @param name - @zh 实体名称 @en Entity name\n     * @returns @zh 创建的实体 @en Created entity\n     */\n    protected createPlayerEntity(playerId: string, name?: string): Entity {\n        const entityName = name ?? `player_${playerId}`;\n        const entity = this.scene.createEntity(entityName);\n        (entity as any)[NETWORK_ENTITY_OWNER] = playerId;\n        this._playerEntities.set(playerId, entity);\n        return entity;\n    }\n\n    /**\n     * @zh 获取玩家的实体\n     * @en Get player's entity\n     */\n    protected getPlayerEntity(playerId: string): Entity | undefined {\n        return this._playerEntities.get(playerId);\n    }\n\n    /**\n     * @zh 销毁玩家的实体\n     * @en Destroy player's entity\n     */\n    protected destroyPlayerEntity(playerId: string): void {\n        const entity = this._playerEntities.get(playerId);\n        if (entity) {\n            const despawnData = encodeDespawn(entity.id);\n            this.broadcastBinary(despawnData);\n            entity.destroy();\n            this._playerEntities.delete(playerId);\n        }\n    }\n\n    // =========================================================================\n    // State Sync | 状态同步\n    // =========================================================================\n\n    /**\n     * @zh 广播二进制数据\n     * @en Broadcast binary data\n     */\n    protected broadcastBinary(data: Uint8Array): void {\n        for (const player of this.players) {\n            this.sendBinary(player, data);\n        }\n    }\n\n    /**\n     * @zh 发送二进制数据给指定玩家\n     * @en Send binary data to specific player\n     */\n    protected sendBinary(player: Player<TPlayerData>, data: Uint8Array): void {\n        player.send('$sync', { data: Array.from(data) });\n    }\n\n    /**\n     * @zh 发送完整状态给玩家（用于玩家刚加入时）\n     * @en Send full state to player (for when player just joined)\n     */\n    protected sendFullState(player: Player<TPlayerData>): void {\n        const entities = this._getSyncEntities();\n        if (entities.length === 0) return;\n\n        for (const entity of entities) {\n            this._initComponentTrackers(entity);\n        }\n\n        const data = encodeSnapshot(entities, SyncOperation.FULL);\n        this.sendBinary(player, data);\n    }\n\n    /**\n     * @zh 广播实体生成\n     * @en Broadcast entity spawn\n     */\n    protected broadcastSpawn(entity: Entity, prefabType?: string): void {\n        this._initComponentTrackers(entity);\n        const data = encodeSpawn(entity, prefabType);\n        this.broadcastBinary(data);\n    }\n\n    /**\n     * @zh 广播增量状态更新\n     * @en Broadcast delta state update\n     */\n    protected broadcastDelta(): void {\n        const entities = this._getSyncEntities();\n        const changedEntities = entities.filter(entity => this._hasChanges(entity));\n\n        if (changedEntities.length === 0) return;\n\n        const data = encodeSnapshot(changedEntities, SyncOperation.DELTA);\n        this.broadcastBinary(data);\n        this._clearChangeTrackers(changedEntities);\n    }\n\n    // =========================================================================\n    // Lifecycle Overrides | 生命周期重载\n    // =========================================================================\n\n    /**\n     * @zh 游戏循环，处理状态同步\n     * @en Game tick, handles state sync\n     */\n    override onTick(_dt: number): void {\n        if (this.ecsConfig.enableDeltaSync) {\n            const now = Date.now();\n            if (now - this._lastSyncTime >= this.ecsConfig.syncInterval) {\n                this._lastSyncTime = now;\n                this.broadcastDelta();\n            }\n        }\n    }\n\n    /**\n     * @zh 玩家离开时自动销毁其实体\n     * @en Auto destroy player entity when leaving\n     */\n    override async onLeave(player: Player<TPlayerData>, reason?: string): Promise<void> {\n        this.destroyPlayerEntity(player.id);\n    }\n\n    /**\n     * @zh 房间销毁时从 WorldManager 移除 World\n     * @en Remove World from WorldManager when room is disposed\n     */\n    override onDispose(): void {\n        this._playerEntities.clear();\n        Core.worldManager.removeWorld(this.worldId);\n    }\n\n    // =========================================================================\n    // Internal | 内部方法\n    // =========================================================================\n\n    private _getSyncEntities(): Entity[] {\n        const entities: Entity[] = [];\n        for (const entity of this.scene.entities.buffer) {\n            if (this._hasSyncComponents(entity)) {\n                entities.push(entity);\n            }\n        }\n        return entities;\n    }\n\n    private _hasSyncComponents(entity: Entity): boolean {\n        for (const component of entity.components) {\n            const metadata: SyncMetadata | undefined = (component.constructor as any)[SYNC_METADATA];\n            if (metadata && metadata.fields.length > 0) {\n                return true;\n            }\n        }\n        return false;\n    }\n\n    private _hasChanges(entity: Entity): boolean {\n        for (const component of entity.components) {\n            const tracker = (component as any)[CHANGE_TRACKER] as ChangeTracker | undefined;\n            if (tracker?.hasChanges()) {\n                return true;\n            }\n        }\n        return false;\n    }\n\n    private _initComponentTrackers(entity: Entity): void {\n        for (const component of entity.components) {\n            const metadata: SyncMetadata | undefined = (component.constructor as any)[SYNC_METADATA];\n            if (metadata && metadata.fields.length > 0) {\n                initChangeTracker(component);\n            }\n        }\n    }\n\n    private _clearChangeTrackers(entities: Entity[]): void {\n        for (const entity of entities) {\n            for (const component of entity.components) {\n                const tracker = (component as any)[CHANGE_TRACKER] as ChangeTracker | undefined;\n                if (tracker) {\n                    tracker.clear();\n                }\n            }\n        }\n    }\n}\n"]}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { S as ServerConfig, G as GameServer, A as ApiDefinition, M as MsgDefinition } from './index-DgaJIm6-.js';
 export { b as ApiContext, c as MsgContext, a as ServerConnection } from './index-DgaJIm6-.js';
 export { I as IPlayer, P as Player, R as Room, a as RoomOptions } from './Room-BnKpl5Sj.js';
+export { o as onMessage } from './decorators-DY8nZ8Nh.js';
 export { ErrorCode, RpcError } from '@esengine/rpc';
 
 /**
@@ -70,29 +71,4 @@ declare function defineApi<TReq, TRes, TData = Record<string, unknown>>(definiti
  */
 declare function defineMsg<TMsg, TData = Record<string, unknown>>(definition: MsgDefinition<TMsg, TData>): MsgDefinition<TMsg, TData>;
 
-/**
- * @zh 房间装饰器
- * @en Room decorators
- */
-/**
- * @zh 消息处理器装饰器
- * @en Message handler decorator
- *
- * @example
- * ```typescript
- * class GameRoom extends Room {
- *     @onMessage('Move')
- *     handleMove(data: { x: number, y: number }, player: Player) {
- *         // handle move
- *     }
- *
- *     @onMessage('Chat')
- *     handleChat(data: { text: string }, player: Player) {
- *         this.broadcast('Chat', { from: player.id, text: data.text })
- *     }
- * }
- * ```
- */
-declare function onMessage(type: string): MethodDecorator;
-
-export { ApiDefinition, GameServer, MsgDefinition, ServerConfig, createServer, defineApi, defineMsg, onMessage };
+export { ApiDefinition, GameServer, MsgDefinition, ServerConfig, createServer, defineApi, defineMsg };

package/dist/index.js

@@ -1,4 +1,5 @@
-export { Player, Room, createServer, onMessage } from './chunk-7C6JZO4O.js';
+export { createServer } from './chunk-QWEIP5QH.js';
+export { Player, Room, onMessage } from './chunk-O3VN2QVN.js';
 import { __name } from './chunk-T626JPC7.js';
 export { ErrorCode, RpcError } from '@esengine/rpc';
 

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/helpers/define.ts"],"names":["defineApi","definition","defineMsg"],"mappings":";;;;;AAwBO,SAASA,UACZC,UAAAA,EAA4C;AAE5C,EAAA,OAAOA,UAAAA;AACX;AAJgBD,MAAAA,CAAAA,SAAAA,EAAAA,WAAAA,CAAAA;AAsBT,SAASE,UACZD,UAAAA,EAAsC;AAEtC,EAAA,OAAOA,UAAAA;AACX;AAJgBC,MAAAA,CAAAA,SAAAA,EAAAA,WAAAA,CAAAA","file":"index.js","sourcesContent":["/**\n * @zh API 和消息定义助手\n * @en API and message definition helpers\n */\n\nimport type { ApiDefinition, MsgDefinition } from '../types/index.js'\n\n/**\n * @zh 定义 API 处理器\n * @en Define API handler\n *\n * @example\n * ```typescript\n * // src/api/join.ts\n * import { defineApi } from '@esengine/server'\n *\n * export default defineApi<ReqJoin, ResJoin>({\n *     handler(req, ctx) {\n *         ctx.conn.data.playerId = generateId()\n *         return { playerId: ctx.conn.data.playerId }\n *     }\n * })\n * ```\n */\nexport function defineApi<TReq, TRes, TData = Record<string, unknown>>(\n    definition: ApiDefinition<TReq, TRes, TData>\n): ApiDefinition<TReq, TRes, TData> {\n    return definition\n}\n\n/**\n * @zh 定义消息处理器\n * @en Define message handler\n *\n * @example\n * ```typescript\n * // src/msg/input.ts\n * import { defineMsg } from '@esengine/server'\n *\n * export default defineMsg<MsgInput>({\n *     handler(msg, ctx) {\n *         console.log('Input from', ctx.conn.id, msg)\n *     }\n * })\n * ```\n */\nexport function defineMsg<TMsg, TData = Record<string, unknown>>(\n    definition: MsgDefinition<TMsg, TData>\n): MsgDefinition<TMsg, TData> {\n    return definition\n}\n"]}
+{"version":3,"sources":["../src/helpers/define.ts"],"names":["defineApi","definition","defineMsg"],"mappings":";;;;;;AAwBO,SAASA,UACZC,UAAAA,EAA4C;AAE5C,EAAA,OAAOA,UAAAA;AACX;AAJgBD,MAAAA,CAAAA,SAAAA,EAAAA,WAAAA,CAAAA;AAsBT,SAASE,UACZD,UAAAA,EAAsC;AAEtC,EAAA,OAAOA,UAAAA;AACX;AAJgBC,MAAAA,CAAAA,SAAAA,EAAAA,WAAAA,CAAAA","file":"index.js","sourcesContent":["/**\n * @zh API 和消息定义助手\n * @en API and message definition helpers\n */\n\nimport type { ApiDefinition, MsgDefinition } from '../types/index.js'\n\n/**\n * @zh 定义 API 处理器\n * @en Define API handler\n *\n * @example\n * ```typescript\n * // src/api/join.ts\n * import { defineApi } from '@esengine/server'\n *\n * export default defineApi<ReqJoin, ResJoin>({\n *     handler(req, ctx) {\n *         ctx.conn.data.playerId = generateId()\n *         return { playerId: ctx.conn.data.playerId }\n *     }\n * })\n * ```\n */\nexport function defineApi<TReq, TRes, TData = Record<string, unknown>>(\n    definition: ApiDefinition<TReq, TRes, TData>\n): ApiDefinition<TReq, TRes, TData> {\n    return definition\n}\n\n/**\n * @zh 定义消息处理器\n * @en Define message handler\n *\n * @example\n * ```typescript\n * // src/msg/input.ts\n * import { defineMsg } from '@esengine/server'\n *\n * export default defineMsg<MsgInput>({\n *     handler(msg, ctx) {\n *         console.log('Input from', ctx.conn.id, msg)\n *     }\n * })\n * ```\n */\nexport function defineMsg<TMsg, TData = Record<string, unknown>>(\n    definition: MsgDefinition<TMsg, TData>\n): MsgDefinition<TMsg, TData> {\n    return definition\n}\n"]}