feat(network): 基于 TSRPC 的网络同步模块 (#318)

- network-protocols: 共享协议包，使用 TSRPC CLI 生成完整类型验证
- network: 浏览器客户端，提供 NetworkPlugin、NetworkService 和同步系统
- network-server: Node.js 服务端，提供 GameServer 和房间管理

packages/network/module.json

@@ -0,0 +1,34 @@
+{
+    "name": "@esengine/network",
+    "displayName": "Network",
+    "description": "TSRPC-based network synchronization for multiplayer games",
+    "version": "1.0.0",
+    "category": "network",
+    "dependencies": [],
+    "components": [
+        {
+            "name": "NetworkIdentity",
+            "displayName": "Network Identity",
+            "description": "Identifies an entity on the network"
+        },
+        {
+            "name": "NetworkTransform",
+            "displayName": "Network Transform",
+            "description": "Syncs entity position and rotation"
+        }
+    ],
+    "systems": [
+        {
+            "name": "NetworkSyncSystem",
+            "description": "Handles state synchronization"
+        },
+        {
+            "name": "NetworkSpawnSystem",
+            "description": "Handles entity spawning/despawning"
+        },
+        {
+            "name": "NetworkInputSystem",
+            "description": "Handles input collection and sending"
+        }
+    ]
+}

packages/network/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "@esengine/network",
+    "version": "1.0.0",
+    "description": "Network synchronization for multiplayer games based on TSRPC",
+    "esengine": {
+        "plugin": true,
+        "pluginExport": "NetworkPlugin",
+        "category": "network",
+        "isEnginePlugin": true
+    },
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsup && tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist",
+        "build:watch": "tsup --watch",
+        "type-check": "tsc --noEmit",
+        "clean": "rimraf dist"
+    },
+    "dependencies": {
+        "@esengine/network-protocols": "workspace:*",
+        "tsrpc-browser": "^3.4.16"
+    },
+    "devDependencies": {
+        "@esengine/ecs-framework": "workspace:*",
+        "@esengine/build-config": "workspace:*",
+        "rimraf": "^5.0.5",
+        "tsup": "^8.0.0",
+        "typescript": "^5.3.3"
+    },
+    "keywords": [
+        "ecs",
+        "network",
+        "multiplayer",
+        "websocket",
+        "sync"
+    ],
+    "author": "yhh",
+    "license": "MIT"
+}

packages/network/src/NetworkPlugin.ts

@@ -0,0 +1,153 @@
+import { type IPlugin, Core, type ServiceContainer, type Scene } from '@esengine/ecs-framework';
+import { NetworkService } from './services/NetworkService';
+import { NetworkSyncSystem } from './systems/NetworkSyncSystem';
+import { NetworkSpawnSystem, type PrefabFactory } from './systems/NetworkSpawnSystem';
+import { NetworkInputSystem } from './systems/NetworkInputSystem';
+
+/**
+ * 网络插件
+ * Network plugin
+ *
+ * 提供基于 TSRPC 的网络同步功能。
+ * Provides TSRPC-based network synchronization.
+ *
+ * @example
+ * ```typescript
+ * import { Core } from '@esengine/ecs-framework';
+ * import { NetworkPlugin } from '@esengine/network';
+ *
+ * const networkPlugin = new NetworkPlugin();
+ * await Core.installPlugin(networkPlugin);
+ *
+ * // 连接到服务器 | Connect to server
+ * await networkPlugin.connect('ws://localhost:3000', 'Player1');
+ *
+ * // 注册预制体 | Register prefab
+ * networkPlugin.registerPrefab('player', (scene, spawn) => {
+ *     const entity = scene.createEntity('Player');
+ *     return entity;
+ * });
+ * ```
+ */
+export class NetworkPlugin implements IPlugin {
+    public readonly name = '@esengine/network';
+    public readonly version = '1.0.0';
+
+    private _networkService!: NetworkService;
+    private _syncSystem!: NetworkSyncSystem;
+    private _spawnSystem!: NetworkSpawnSystem;
+    private _inputSystem!: NetworkInputSystem;
+
+    /**
+     * 网络服务
+     * Network service
+     */
+    get networkService(): NetworkService {
+        return this._networkService;
+    }
+
+    /**
+     * 同步系统
+     * Sync system
+     */
+    get syncSystem(): NetworkSyncSystem {
+        return this._syncSystem;
+    }
+
+    /**
+     * 生成系统
+     * Spawn system
+     */
+    get spawnSystem(): NetworkSpawnSystem {
+        return this._spawnSystem;
+    }
+
+    /**
+     * 输入系统
+     * Input system
+     */
+    get inputSystem(): NetworkInputSystem {
+        return this._inputSystem;
+    }
+
+    /**
+     * 是否已连接
+     * Is connected
+     */
+    get isConnected(): boolean {
+        return this._networkService?.isConnected ?? false;
+    }
+
+    /**
+     * 安装插件
+     * Install plugin
+     */
+    install(_core: Core, _services: ServiceContainer): void {
+        this._networkService = new NetworkService();
+
+        // 当场景加载时添加系统
+        // Add systems when scene loads
+        const scene = Core.scene;
+        if (scene) {
+            this._setupSystems(scene as Scene);
+        }
+    }
+
+    /**
+     * 卸载插件
+     * Uninstall plugin
+     */
+    uninstall(): void {
+        this._networkService?.disconnect();
+    }
+
+    private _setupSystems(scene: Scene): void {
+        this._syncSystem = new NetworkSyncSystem(this._networkService);
+        this._spawnSystem = new NetworkSpawnSystem(this._networkService, this._syncSystem);
+        this._inputSystem = new NetworkInputSystem(this._networkService);
+
+        scene.addSystem(this._syncSystem);
+        scene.addSystem(this._spawnSystem);
+        scene.addSystem(this._inputSystem);
+    }
+
+    /**
+     * 连接到服务器
+     * Connect to server
+     */
+    public async connect(serverUrl: string, playerName: string, roomId?: string): Promise<boolean> {
+        return this._networkService.connect(serverUrl, playerName, roomId);
+    }
+
+    /**
+     * 断开连接
+     * Disconnect
+     */
+    public async disconnect(): Promise<void> {
+        await this._networkService.disconnect();
+    }
+
+    /**
+     * 注册预制体工厂
+     * Register prefab factory
+     */
+    public registerPrefab(prefabType: string, factory: PrefabFactory): void {
+        this._spawnSystem?.registerPrefab(prefabType, factory);
+    }
+
+    /**
+     * 发送移动输入
+     * Send move input
+     */
+    public sendMoveInput(x: number, y: number): void {
+        this._inputSystem?.addMoveInput(x, y);
+    }
+
+    /**
+     * 发送动作输入
+     * Send action input
+     */
+    public sendActionInput(action: string): void {
+        this._inputSystem?.addActionInput(action);
+    }
+}

packages/network/src/components/NetworkIdentity.ts

@@ -0,0 +1,70 @@
+import { Component, ECSComponent, Serialize, Serializable, Property } from '@esengine/ecs-framework';
+
+/**
+ * 网络身份组件
+ * Network identity component
+ *
+ * 标识一个实体在网络上的唯一身份。
+ * Identifies an entity's unique identity on the network.
+ */
+@ECSComponent('NetworkIdentity')
+@Serializable({ version: 1, typeId: 'NetworkIdentity' })
+export class NetworkIdentity extends Component {
+    /**
+     * 网络实体 ID
+     * Network entity ID
+     */
+    @Serialize()
+    @Property({ type: 'integer', label: 'Net ID', readOnly: true })
+    public netId: number = 0;
+
+    /**
+     * 所有者客户端 ID
+     * Owner client ID
+     */
+    @Serialize()
+    @Property({ type: 'integer', label: 'Owner ID', readOnly: true })
+    public ownerId: number = 0;
+
+    /**
+     * 是否为本地玩家拥有
+     * Is owned by local player
+     */
+    public bIsLocalPlayer: boolean = false;
+
+    /**
+     * 是否有权限控制
+     * Has authority
+     */
+    public bHasAuthority: boolean = false;
+
+    /**
+     * 预制体类型
+     * Prefab type
+     */
+    @Serialize()
+    @Property({ type: 'string', label: 'Prefab Type' })
+    public prefabType: string = '';
+
+    /**
+     * 同步间隔 (ms)
+     * Sync interval in milliseconds
+     */
+    @Serialize()
+    @Property({ type: 'number', label: 'Sync Interval', min: 16 })
+    public syncInterval: number = 100;
+
+    /**
+     * 上次同步时间
+     * Last sync time
+     */
+    public lastSyncTime: number = 0;
+
+    /**
+     * 检查是否需要同步
+     * Check if sync is needed
+     */
+    public needsSync(now: number): boolean {
+        return now - this.lastSyncTime >= this.syncInterval;
+    }
+}

packages/network/src/components/NetworkTransform.ts

@@ -0,0 +1,100 @@
+import { Component, ECSComponent, Serialize, Serializable, Property } from '@esengine/ecs-framework';
+
+/**
+ * 网络变换组件
+ * Network transform component
+ *
+ * 同步实体的位置和旋转。支持插值平滑。
+ * Syncs entity position and rotation with interpolation smoothing.
+ */
+@ECSComponent('NetworkTransform', { requires: ['NetworkIdentity'] })
+@Serializable({ version: 1, typeId: 'NetworkTransform' })
+export class NetworkTransform extends Component {
+    /**
+     * 目标位置 X
+     * Target position X
+     */
+    public targetX: number = 0;
+
+    /**
+     * 目标位置 Y
+     * Target position Y
+     */
+    public targetY: number = 0;
+
+    /**
+     * 目标旋转
+     * Target rotation
+     */
+    public targetRotation: number = 0;
+
+    /**
+     * 当前位置 X
+     * Current position X
+     */
+    public currentX: number = 0;
+
+    /**
+     * 当前位置 Y
+     * Current position Y
+     */
+    public currentY: number = 0;
+
+    /**
+     * 当前旋转
+     * Current rotation
+     */
+    public currentRotation: number = 0;
+
+    /**
+     * 插值速度
+     * Interpolation speed
+     */
+    @Serialize()
+    @Property({ type: 'number', label: 'Lerp Speed', min: 0.1, max: 50 })
+    public lerpSpeed: number = 10;
+
+    /**
+     * 是否启用插值
+     * Enable interpolation
+     */
+    @Serialize()
+    @Property({ type: 'boolean', label: 'Interpolate' })
+    public bInterpolate: boolean = true;
+
+    /**
+     * 同步间隔 (ms)
+     * Sync interval in milliseconds
+     */
+    @Serialize()
+    @Property({ type: 'number', label: 'Sync Interval', min: 16 })
+    public syncInterval: number = 50;
+
+    /**
+     * 上次同步时间
+     * Last sync time
+     */
+    public lastSyncTime: number = 0;
+
+    /**
+     * 设置目标位置
+     * Set target position
+     */
+    public setTarget(x: number, y: number, rotation?: number): void {
+        this.targetX = x;
+        this.targetY = y;
+        if (rotation !== undefined) {
+            this.targetRotation = rotation;
+        }
+    }
+
+    /**
+     * 立即跳转到目标位置
+     * Snap to target position immediately
+     */
+    public snap(): void {
+        this.currentX = this.targetX;
+        this.currentY = this.targetY;
+        this.currentRotation = this.targetRotation;
+    }
+}

packages/network/src/index.ts

@@ -0,0 +1,65 @@
+/**
+ * @esengine/network
+ *
+ * 基于 TSRPC 的网络同步模块（客户端）
+ * TSRPC-based network synchronization module (client)
+ */
+
+// ============================================================================
+// Re-export from protocols | 从协议包重新导出
+// ============================================================================
+
+export type {
+    ServiceType,
+    Vec2,
+    IEntityState,
+    IPlayerInput,
+    MsgSync,
+    MsgInput,
+    MsgSpawn,
+    MsgDespawn,
+    ReqJoin,
+    ResJoin
+} from '@esengine/network-protocols';
+
+export { serviceProto } from '@esengine/network-protocols';
+
+// ============================================================================
+// Tokens | 服务令牌
+// ============================================================================
+
+export {
+    NetworkServiceToken,
+    NetworkSyncSystemToken,
+    NetworkSpawnSystemToken,
+    NetworkInputSystemToken
+} from './tokens';
+
+// ============================================================================
+// Plugin | 插件
+// ============================================================================
+
+export { NetworkPlugin } from './NetworkPlugin';
+
+// ============================================================================
+// Services | 服务
+// ============================================================================
+
+export { NetworkService, ENetworkState } from './services/NetworkService';
+export type { INetworkCallbacks } from './services/NetworkService';
+
+// ============================================================================
+// Components | 组件
+// ============================================================================
+
+export { NetworkIdentity } from './components/NetworkIdentity';
+export { NetworkTransform } from './components/NetworkTransform';
+
+// ============================================================================
+// Systems | 系统
+// ============================================================================
+
+export { NetworkSyncSystem } from './systems/NetworkSyncSystem';
+export { NetworkSpawnSystem } from './systems/NetworkSpawnSystem';
+export type { PrefabFactory } from './systems/NetworkSpawnSystem';
+export { NetworkInputSystem } from './systems/NetworkInputSystem';

packages/network/src/services/NetworkService.ts

@@ -0,0 +1,172 @@
+import { WsClient } from 'tsrpc-browser';
+import {
+    serviceProto,
+    type ServiceType,
+    type MsgSync,
+    type MsgSpawn,
+    type MsgDespawn,
+    type IPlayerInput
+} from '@esengine/network-protocols';
+
+/**
+ * 连接状态
+ * Connection state
+ */
+export const enum ENetworkState {
+    Disconnected = 0,
+    Connecting = 1,
+    Connected = 2
+}
+
+/**
+ * 网络事件回调
+ * Network event callbacks
+ */
+export interface INetworkCallbacks {
+    onConnected?: (clientId: number, roomId: string) => void;
+    onDisconnected?: () => void;
+    onSync?: (msg: MsgSync) => void;
+    onSpawn?: (msg: MsgSpawn) => void;
+    onDespawn?: (msg: MsgDespawn) => void;
+    onError?: (error: Error) => void;
+}
+
+/**
+ * 创建 TSRPC 客户端
+ * Create TSRPC client
+ */
+function createClient(serverUrl: string): WsClient<ServiceType> {
+    return new WsClient(serviceProto, {
+        server: serverUrl,
+        json: true,
+        logLevel: 'warn'
+    });
+}
+
+/**
+ * 网络服务
+ * Network service
+ *
+ * 基于 TSRPC 的网络服务封装，提供类型安全的网络通信。
+ * TSRPC-based network service wrapper with type-safe communication.
+ */
+export class NetworkService {
+    private _client: WsClient<ServiceType> | null = null;
+    private _state: ENetworkState = ENetworkState.Disconnected;
+    private _clientId: number = 0;
+    private _roomId: string = '';
+    private _callbacks: INetworkCallbacks = {};
+
+    get state(): ENetworkState {
+        return this._state;
+    }
+
+    get clientId(): number {
+        return this._clientId;
+    }
+
+    get roomId(): string {
+        return this._roomId;
+    }
+
+    get isConnected(): boolean {
+        return this._state === ENetworkState.Connected;
+    }
+
+    /**
+     * 设置回调
+     * Set callbacks
+     */
+    setCallbacks(callbacks: INetworkCallbacks): void {
+        this._callbacks = { ...this._callbacks, ...callbacks };
+    }
+
+    /**
+     * 连接到服务器
+     * Connect to server
+     */
+    async connect(serverUrl: string, playerName: string, roomId?: string): Promise<boolean> {
+        if (this._state !== ENetworkState.Disconnected) {
+            return false;
+        }
+
+        this._state = ENetworkState.Connecting;
+        this._client = createClient(serverUrl);
+        this._setupListeners();
+
+        // 连接
+        // Connect
+        const connectResult = await this._client.connect();
+        if (!connectResult.isSucc) {
+            this._state = ENetworkState.Disconnected;
+            this._callbacks.onError?.(new Error(connectResult.errMsg));
+            return false;
+        }
+
+        // 加入房间
+        // Join room
+        const joinResult = await this._client.callApi('Join', {
+            playerName,
+            roomId
+        });
+
+        if (!joinResult.isSucc) {
+            await this._client.disconnect();
+            this._state = ENetworkState.Disconnected;
+            this._callbacks.onError?.(new Error(joinResult.err.message));
+            return false;
+        }
+
+        this._clientId = joinResult.res.clientId;
+        this._roomId = joinResult.res.roomId;
+        this._state = ENetworkState.Connected;
+        this._callbacks.onConnected?.(this._clientId, this._roomId);
+
+        return true;
+    }
+
+    /**
+     * 断开连接
+     * Disconnect
+     */
+    async disconnect(): Promise<void> {
+        if (this._client) {
+            await this._client.disconnect();
+        }
+        this._state = ENetworkState.Disconnected;
+        this._clientId = 0;
+        this._roomId = '';
+        this._client = null;
+    }
+
+    /**
+     * 发送输入
+     * Send input
+     */
+    sendInput(input: IPlayerInput): void {
+        if (!this.isConnected || !this._client) return;
+        this._client.sendMsg('Input', { input });
+    }
+
+    private _setupListeners(): void {
+        if (!this._client) return;
+
+        this._client.listenMsg('Sync', (msg) => {
+            this._callbacks.onSync?.(msg);
+        });
+
+        this._client.listenMsg('Spawn', (msg) => {
+            this._callbacks.onSpawn?.(msg);
+        });
+
+        this._client.listenMsg('Despawn', (msg) => {
+            this._callbacks.onDespawn?.(msg);
+        });
+
+        this._client.flows.postDisconnectFlow.push((v) => {
+            this._state = ENetworkState.Disconnected;
+            this._callbacks.onDisconnected?.();
+            return v;
+        });
+    }
+}

packages/network/src/systems/NetworkInputSystem.ts

@@ -0,0 +1,73 @@
+import { EntitySystem, Matcher } from '@esengine/ecs-framework';
+import type { IPlayerInput } from '@esengine/network-protocols';
+import type { NetworkService } from '../services/NetworkService';
+
+/**
+ * 网络输入系统
+ * Network input system
+ *
+ * 收集本地玩家输入并发送到服务器。
+ * Collects local player input and sends to server.
+ */
+export class NetworkInputSystem extends EntitySystem {
+    private _networkService: NetworkService;
+    private _frame: number = 0;
+    private _inputQueue: IPlayerInput[] = [];
+
+    constructor(networkService: NetworkService) {
+        // 不查询任何实体，此系统只处理输入
+        // Don't query any entities, this system only handles input
+        super(Matcher.nothing());
+        this._networkService = networkService;
+    }
+
+    /**
+     * 处理输入队列
+     * Process input queue
+     */
+    protected override process(): void {
+        if (!this._networkService.isConnected) return;
+
+        this._frame++;
+
+        // 发送队列中的输入
+        // Send queued inputs
+        while (this._inputQueue.length > 0) {
+            const input = this._inputQueue.shift()!;
+            input.frame = this._frame;
+            this._networkService.sendInput(input);
+        }
+    }
+
+    /**
+     * 添加移动输入
+     * Add move input
+     */
+    public addMoveInput(x: number, y: number): void {
+        this._inputQueue.push({
+            frame: 0,
+            moveDir: { x, y }
+        });
+    }
+
+    /**
+     * 添加动作输入
+     * Add action input
+     */
+    public addActionInput(action: string): void {
+        const lastInput = this._inputQueue[this._inputQueue.length - 1];
+        if (lastInput) {
+            lastInput.actions = lastInput.actions || [];
+            lastInput.actions.push(action);
+        } else {
+            this._inputQueue.push({
+                frame: 0,
+                actions: [action]
+            });
+        }
+    }
+
+    protected override onDestroy(): void {
+        this._inputQueue.length = 0;
+    }
+}

packages/network/src/systems/NetworkSpawnSystem.ts

@@ -0,0 +1,101 @@
+import { EntitySystem, Entity, type Scene, Matcher } from '@esengine/ecs-framework';
+import type { MsgSpawn, MsgDespawn } from '@esengine/network-protocols';
+import { NetworkIdentity } from '../components/NetworkIdentity';
+import { NetworkTransform } from '../components/NetworkTransform';
+import type { NetworkService } from '../services/NetworkService';
+import type { NetworkSyncSystem } from './NetworkSyncSystem';
+
+/**
+ * 预制体工厂函数类型
+ * Prefab factory function type
+ */
+export type PrefabFactory = (scene: Scene, spawn: MsgSpawn) => Entity;
+
+/**
+ * 网络生成系统
+ * Network spawn system
+ *
+ * 处理网络实体的生成和销毁。
+ * Handles spawning and despawning of networked entities.
+ */
+export class NetworkSpawnSystem extends EntitySystem {
+    private _networkService: NetworkService;
+    private _syncSystem: NetworkSyncSystem;
+    private _prefabFactories: Map<string, PrefabFactory> = new Map();
+
+    constructor(networkService: NetworkService, syncSystem: NetworkSyncSystem) {
+        // 不查询任何实体，此系统只响应网络消息
+        // Don't query any entities, this system only responds to network messages
+        super(Matcher.nothing());
+        this._networkService = networkService;
+        this._syncSystem = syncSystem;
+    }
+
+    protected override onInitialize(): void {
+        this._networkService.setCallbacks({
+            onSpawn: this._handleSpawn.bind(this),
+            onDespawn: this._handleDespawn.bind(this)
+        });
+    }
+
+    /**
+     * 注册预制体工厂
+     * Register prefab factory
+     */
+    public registerPrefab(prefabType: string, factory: PrefabFactory): void {
+        this._prefabFactories.set(prefabType, factory);
+    }
+
+    /**
+     * 注销预制体工厂
+     * Unregister prefab factory
+     */
+    public unregisterPrefab(prefabType: string): void {
+        this._prefabFactories.delete(prefabType);
+    }
+
+    private _handleSpawn(msg: MsgSpawn): void {
+        if (!this.scene) return;
+
+        const factory = this._prefabFactories.get(msg.prefab);
+        if (!factory) {
+            this.logger.warn(`Unknown prefab: ${msg.prefab}`);
+            return;
+        }
+
+        const entity = factory(this.scene, msg);
+
+        // 添加网络组件
+        // Add network components
+        const identity = entity.addComponent(new NetworkIdentity());
+        identity.netId = msg.netId;
+        identity.ownerId = msg.ownerId;
+        identity.prefabType = msg.prefab;
+        identity.bHasAuthority = msg.ownerId === this._networkService.clientId;
+        identity.bIsLocalPlayer = identity.bHasAuthority;
+
+        const transform = entity.addComponent(new NetworkTransform());
+        transform.setTarget(msg.pos.x, msg.pos.y, msg.rot);
+        transform.snap();
+
+        // 注册到同步系统
+        // Register to sync system
+        this._syncSystem.registerEntity(msg.netId, entity.id);
+    }
+
+    private _handleDespawn(msg: MsgDespawn): void {
+        const entityId = this._syncSystem.getEntityId(msg.netId);
+        if (entityId === undefined) return;
+
+        const entity = this.scene?.findEntityById(entityId);
+        if (entity) {
+            entity.destroy();
+        }
+
+        this._syncSystem.unregisterEntity(msg.netId);
+    }
+
+    protected override onDestroy(): void {
+        this._prefabFactories.clear();
+    }
+}

packages/network/src/systems/NetworkSyncSystem.ts

@@ -0,0 +1,104 @@
+import { EntitySystem, Matcher, Time, type Entity } from '@esengine/ecs-framework';
+import type { MsgSync } from '@esengine/network-protocols';
+import { NetworkIdentity } from '../components/NetworkIdentity';
+import { NetworkTransform } from '../components/NetworkTransform';
+import type { NetworkService } from '../services/NetworkService';
+
+/**
+ * 网络同步系统
+ * Network sync system
+ *
+ * 处理网络实体的状态同步和插值。
+ * Handles state synchronization and interpolation for networked entities.
+ */
+export class NetworkSyncSystem extends EntitySystem {
+    private _networkService: NetworkService;
+    private _netIdToEntity: Map<number, number> = new Map();
+
+    constructor(networkService: NetworkService) {
+        super(Matcher.all(NetworkIdentity, NetworkTransform));
+        this._networkService = networkService;
+    }
+
+    protected override onInitialize(): void {
+        this._networkService.setCallbacks({
+            onSync: this._handleSync.bind(this)
+        });
+    }
+
+    /**
+     * 处理实体列表
+     * Process entities
+     */
+    protected override process(entities: readonly Entity[]): void {
+        const deltaTime = Time.deltaTime;
+
+        for (const entity of entities) {
+            const transform = this.requireComponent(entity, NetworkTransform);
+            const identity = this.requireComponent(entity, NetworkIdentity);
+
+            // 只有非本地玩家需要插值
+            // Only non-local players need interpolation
+            if (!identity.bHasAuthority && transform.bInterpolate) {
+                this._interpolate(transform, deltaTime);
+            }
+        }
+    }
+
+    /**
+     * 注册网络实体
+     * Register network entity
+     */
+    public registerEntity(netId: number, entityId: number): void {
+        this._netIdToEntity.set(netId, entityId);
+    }
+
+    /**
+     * 注销网络实体
+     * Unregister network entity
+     */
+    public unregisterEntity(netId: number): void {
+        this._netIdToEntity.delete(netId);
+    }
+
+    /**
+     * 根据网络 ID 获取实体 ID
+     * Get entity ID by network ID
+     */
+    public getEntityId(netId: number): number | undefined {
+        return this._netIdToEntity.get(netId);
+    }
+
+    private _handleSync(msg: MsgSync): void {
+        for (const state of msg.entities) {
+            const entityId = this._netIdToEntity.get(state.netId);
+            if (entityId === undefined) continue;
+
+            const entity = this.scene?.findEntityById(entityId);
+            if (!entity) continue;
+
+            const transform = entity.getComponent(NetworkTransform);
+            if (transform && state.pos) {
+                transform.setTarget(state.pos.x, state.pos.y, state.rot);
+            }
+        }
+    }
+
+    private _interpolate(transform: NetworkTransform, deltaTime: number): void {
+        const t = Math.min(1, transform.lerpSpeed * deltaTime);
+
+        transform.currentX += (transform.targetX - transform.currentX) * t;
+        transform.currentY += (transform.targetY - transform.currentY) * t;
+
+        // 角度插值需要处理环绕
+        // Angle interpolation needs to handle wrap-around
+        let angleDiff = transform.targetRotation - transform.currentRotation;
+        while (angleDiff > Math.PI) angleDiff -= Math.PI * 2;
+        while (angleDiff < -Math.PI) angleDiff += Math.PI * 2;
+        transform.currentRotation += angleDiff * t;
+    }
+
+    protected override onDestroy(): void {
+        this._netIdToEntity.clear();
+    }
+}

packages/network/src/tokens.ts

@@ -0,0 +1,38 @@
+/**
+ * Network 模块服务令牌
+ * Network module service tokens
+ */
+
+import { createServiceToken } from '@esengine/ecs-framework';
+import type { NetworkService } from './services/NetworkService';
+import type { NetworkSyncSystem } from './systems/NetworkSyncSystem';
+import type { NetworkSpawnSystem } from './systems/NetworkSpawnSystem';
+import type { NetworkInputSystem } from './systems/NetworkInputSystem';
+
+// ============================================================================
+// Network 模块导出的令牌 | Tokens exported by Network module
+// ============================================================================
+
+/**
+ * 网络服务令牌
+ * Network service token
+ */
+export const NetworkServiceToken = createServiceToken<NetworkService>('networkService');
+
+/**
+ * 网络同步系统令牌
+ * Network sync system token
+ */
+export const NetworkSyncSystemToken = createServiceToken<NetworkSyncSystem>('networkSyncSystem');
+
+/**
+ * 网络生成系统令牌
+ * Network spawn system token
+ */
+export const NetworkSpawnSystemToken = createServiceToken<NetworkSpawnSystem>('networkSpawnSystem');
+
+/**
+ * 网络输入系统令牌
+ * Network input system token
+ */
+export const NetworkInputSystemToken = createServiceToken<NetworkInputSystem>('networkInputSystem');

packages/network/tsconfig.build.json

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

packages/network/tsconfig.json

@@ -0,0 +1,15 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "composite": true,
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "moduleResolution": "node"
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist"],
+    "references": [
+        { "path": "../core" },
+        { "path": "../network-protocols" }
+    ]
+}

packages/network/tsup.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'tsup';
+import { runtimeOnlyPreset } from '../build-config/src/presets/plugin-tsup';
+
+export default defineConfig({
+    ...runtimeOnlyPreset({
+        external: [/^tsrpc/, 'tsbuffer', 'tsbuffer-schema']
+    }),
+    tsconfig: 'tsconfig.build.json',
+    // 禁用 tsup 的 DTS 捆绑器，改用 tsc 生成声明文件
+    // tsup 的 DTS bundler 无法正确解析 tsrpc 的类型继承链
+    // Disable tsup's DTS bundler, use tsc to generate declarations
+    // tsup's DTS bundler cannot correctly resolve tsrpc's type inheritance chain
+    dts: false
+});