API 参考

NetworkPlugin

客户端网络插件核心类。

class NetworkPlugin implements IPlugin {
    readonly name: string;
    readonly version: string;

    // 访问器
    get networkService(): GameNetworkService;
    get syncSystem(): NetworkSyncSystem;
    get spawnSystem(): NetworkSpawnSystem;
    get inputSystem(): NetworkInputSystem;
    get localPlayerId(): number;
    get isConnected(): boolean;

    // 生命周期
    install(core: Core, services: ServiceContainer): void;
    uninstall(): void;

    // 连接管理
    connect(options: NetworkServiceOptions & {
        playerName: string;
        roomId?: string;
    }): Promise<boolean>;
    disconnect(): Promise<void>;

    // 预制体注册
    registerPrefab(prefabType: string, factory: PrefabFactory): void;

    // 输入发送
    sendMoveInput(x: number, y: number): void;
    sendActionInput(action: string): void;
}

RpcService

通用 RPC 服务基类，支持自定义协议。

class RpcService<P extends ProtocolDef> {
    // 访问器
    get state(): NetworkState;
    get isConnected(): boolean;
    get client(): RpcClient<P> | null;

    constructor(protocol: P);

    // 连接管理
    connect(options: NetworkServiceOptions): Promise<void>;
    disconnect(): void;

    // RPC 调用
    call<K extends ApiNames<P>>(
        name: K,
        input: ApiInput<P['api'][K]>
    ): Promise<ApiOutput<P['api'][K]>>;

    // 消息发送
    send<K extends MsgNames<P>>(name: K, data: MsgData<P['msg'][K]>): void;

    // 消息监听
    on<K extends MsgNames<P>>(name: K, handler: (data: MsgData<P['msg'][K]>) => void): this;
    off<K extends MsgNames<P>>(name: K, handler?: (data: MsgData<P['msg'][K]>) => void): this;
    once<K extends MsgNames<P>>(name: K, handler: (data: MsgData<P['msg'][K]>) => void): this;
}

GameNetworkService

游戏网络服务，继承自 RpcService，提供游戏特定的便捷方法。

class GameNetworkService extends RpcService<GameProtocol> {
    // 发送玩家输入
    sendInput(input: PlayerInput): void;

    // 监听状态同步（链式调用）
    onSync(handler: (data: SyncData) => void): this;

    // 监听实体生成
    onSpawn(handler: (data: SpawnData) => void): this;

    // 监听实体销毁
    onDespawn(handler: (data: DespawnData) => void): this;
}

枚举类型

NetworkState

const enum NetworkState {
    Disconnected = 0,
    Connecting = 1,
    Connected = 2
}

接口类型

NetworkServiceOptions

interface NetworkServiceOptions extends RpcClientOptions {
    url: string;
}

RpcClientOptions

interface RpcClientOptions {
    codec?: Codec;
    onConnect?: () => void;
    onDisconnect?: (reason?: string) => void;
    onError?: (error: Error) => void;
}

PrefabFactory

type PrefabFactory = (scene: Scene, spawn: SpawnData) => Entity;

PlayerInput

interface PlayerInput {
    frame: number;
    moveDir?: { x: number; y: number };
    actions?: string[];
}

组件

NetworkIdentity

class NetworkIdentity extends Component {
    netId: number;
    ownerId: number;
    bIsLocalPlayer: boolean;
    bHasAuthority: boolean;
}

NetworkTransform

class NetworkTransform extends Component {
    position: { x: number; y: number };
    rotation: number;
    velocity: { x: number; y: number };
}

系统

NetworkSyncSystem

class NetworkSyncSystem extends EntitySystem {
    // 内部使用，由 NetworkPlugin 自动管理
}

NetworkSpawnSystem

class NetworkSpawnSystem extends EntitySystem {
    registerPrefab(prefabType: string, factory: PrefabFactory): void;
}

NetworkInputSystem

class NetworkInputSystem extends EntitySystem {
    addMoveInput(x: number, y: number): void;
    addActionInput(action: string): void;
    clearInput(): void;
}

服务令牌

import {
    NetworkServiceToken,
    NetworkSyncSystemToken,
    NetworkSpawnSystemToken,
    NetworkInputSystemToken
} from '@esengine/network';

// 使用
const networkService = services.get(NetworkServiceToken);

服务器端 API

RpcServer

class RpcServer<P extends ProtocolDef> {
    constructor(protocol: P, options: RpcServerOptions);

    // 启动/停止服务器
    start(): Promise<void>;
    stop(): void;

    // 注册 API 处理器
    handle<K extends ApiNames<P>>(
        name: K,
        handler: (input: ApiInput<P['api'][K]>, ctx: RpcContext) => Promise<ApiOutput<P['api'][K]>>
    ): void;

    // 广播消息
    broadcast<K extends MsgNames<P>>(name: K, data: MsgData<P['msg'][K]>): void;

    // 发送给特定客户端
    sendTo<K extends MsgNames<P>>(clientId: string, name: K, data: MsgData<P['msg'][K]>): void;
}

RpcServerOptions

interface RpcServerOptions {
    port: number;
    codec?: Codec;
    onStart?: (port: number) => void;
    onConnection?: (clientId: string) => void;
    onDisconnection?: (clientId: string, reason?: string) => void;
    onError?: (error: Error) => void;
}

RpcContext

interface RpcContext {
    clientId: string;
}

协议定义

gameProtocol

默认游戏协议，包含加入/离开 API 和状态同步消息：

const gameProtocol = rpc.define({
    api: {
        join: rpc.api<JoinRequest, JoinResponse>(),
        leave: rpc.api<void, void>(),
    },
    msg: {
        input: rpc.msg<PlayerInput>(),
        sync: rpc.msg<SyncData>(),
        spawn: rpc.msg<SpawnData>(),
        despawn: rpc.msg<DespawnData>(),
    },
});

协议消息类型

SyncData

interface SyncData {
    time: number;
    entities: IEntityState[];
}

SpawnData

interface SpawnData {
    netId: number;
    ownerId: number;
    prefab: string;
    position: { x: number; y: number };
    rotation: number;
}

DespawnData

interface DespawnData {
    netId: number;
}

JoinRequest

interface JoinRequest {
    playerName: string;
    roomId?: string;
}

JoinResponse

interface JoinResponse {
    playerId: number;
    roomId: string;
}

EntitySyncState

interface EntitySyncState {
    netId: number;
    position?: { x: number; y: number };
    rotation?: number;
}

工具函数

createSnapshotBuffer

function createSnapshotBuffer<T>(config: {
    maxSnapshots: number;
    interpolationDelay: number;
}): ISnapshotBuffer<T>;

createTransformInterpolator

function createTransformInterpolator(): ITransformInterpolator;

createHermiteTransformInterpolator

function createHermiteTransformInterpolator(config: {
    bufferSize: number;
}): IHermiteTransformInterpolator;

createClientPrediction

function createClientPrediction(config: {
    maxPredictedInputs: number;
    reconciliationThreshold: number;
}): IClientPrediction;