客户端预测

客户端预测是网络游戏中用于减少输入延迟的关键技术。通过在本地立即应用玩家输入，同时等待服务器确认，可以让游戏感觉更加流畅响应。

NetworkPredictionSystem

NetworkPredictionSystem 是专门处理本地玩家预测的 ECS 系统。

基本用法

import { NetworkPlugin } from '@esengine/network';

const networkPlugin = new NetworkPlugin({
    enablePrediction: true,
    predictionConfig: {
        moveSpeed: 200,           // 移动速度（单位/秒）
        maxUnacknowledgedInputs: 60,  // 最大未确认输入数
        reconciliationThreshold: 0.5,  // 校正阈值
        reconciliationSpeed: 10,       // 校正速度
    }
});

await Core.installPlugin(networkPlugin);

设置本地玩家

当本地玩家实体生成后，需要设置其网络 ID：

networkPlugin.registerPrefab('player', (scene, spawn) => {
    const entity = scene.createEntity(`player_${spawn.netId}`);

    const identity = entity.addComponent(new NetworkIdentity());
    identity.netId = spawn.netId;
    identity.ownerId = spawn.ownerId;
    identity.bHasAuthority = spawn.ownerId === networkPlugin.localPlayerId;
    identity.bIsLocalPlayer = identity.bHasAuthority;

    entity.addComponent(new NetworkTransform());

    // 设置本地玩家用于预测
    if (identity.bIsLocalPlayer) {
        networkPlugin.setLocalPlayerNetId(spawn.netId);
    }

    return entity;
});

发送输入

// 在游戏循环中发送移动输入
function onUpdate() {
    const moveX = Input.getAxis('horizontal');
    const moveY = Input.getAxis('vertical');

    if (moveX !== 0 || moveY !== 0) {
        networkPlugin.sendMoveInput(moveX, moveY);
    }

    // 发送动作输入
    if (Input.isPressed('attack')) {
        networkPlugin.sendActionInput('attack');
    }
}

预测配置

属性	类型	默认值	描述
moveSpeed	number	200	移动速度（单位/秒）
enabled	boolean	true	是否启用预测
maxUnacknowledgedInputs	number	60	最大未确认输入数
reconciliationThreshold	number	0.5	触发校正的位置差异阈值
reconciliationSpeed	number	10	校正平滑速度

工作原理

客户端                              服务器
   │                                   │
   ├─ 1. 捕获输入 (seq=1)              │
   ├─ 2. 本地预测移动                   │
   ├─ 3. 发送输入到服务器 ──────────────►
   │                                   │
   ├─ 4. 继续捕获输入 (seq=2,3...)     │
   ├─ 5. 继续本地预测                   │
   │                                   │
   │                                   ├─ 6. 处理输入 (seq=1)
   │                                   │
   ◄──────── 7. 返回状态 (ackSeq=1) ────
   │                                   │
   ├─ 8. 比较预测和服务器状态           │
   ├─ 9. 重放 seq=2,3... 的输入        │
   ├─ 10. 平滑校正到正确位置            │
   │                                   │

步骤详解

1. 输入捕获：捕获玩家输入并分配序列号
2. 本地预测：立即应用输入到本地状态
3. 发送输入：将输入发送到服务器
4. 缓存输入：保存输入用于后续校正
5. 接收确认：服务器返回权威状态和已确认序列号
6. 状态比较：比较预测状态和服务器状态
7. 输入重放：使用缓存的未确认输入重新计算状态
8. 平滑校正：平滑插值到正确位置

底层 API

如果需要更细粒度的控制，可以直接使用 ClientPrediction 类：

import { createClientPrediction, type IPredictor } from '@esengine/network';

// 定义状态类型
interface PlayerState {
    x: number;
    y: number;
    rotation: number;
}

// 定义输入类型
interface PlayerInput {
    dx: number;
    dy: number;
}

// 定义预测器
const predictor: IPredictor<PlayerState, PlayerInput> = {
    predict(state: PlayerState, input: PlayerInput, dt: number): PlayerState {
        return {
            x: state.x + input.dx * MOVE_SPEED * dt,
            y: state.y + input.dy * MOVE_SPEED * dt,
            rotation: state.rotation,
        };
    }
};

// 创建客户端预测
const prediction = createClientPrediction(predictor, {
    maxUnacknowledgedInputs: 60,
    reconciliationThreshold: 0.5,
    reconciliationSpeed: 10,
});

// 记录输入并获取预测状态
const input = { dx: 1, dy: 0 };
const predictedState = prediction.recordInput(input, currentState, deltaTime);

// 获取要发送的输入
const inputToSend = prediction.getInputToSend();

// 与服务器状态校正
prediction.reconcile(
    serverState,
    serverAckSeq,
    (state) => ({ x: state.x, y: state.y }),
    deltaTime
);

// 获取校正偏移
const offset = prediction.correctionOffset;

启用/禁用预测

// 运行时切换预测
networkPlugin.setPredictionEnabled(false);

// 检查预测状态
if (networkPlugin.isPredictionEnabled) {
    console.log('Prediction is active');
}

最佳实践

1. 合理设置校正阈值

// 动作游戏：较低阈值，更精确
predictionConfig: {
    reconciliationThreshold: 0.1,
}

// 休闲游戏：较高阈值，更平滑
predictionConfig: {
    reconciliationThreshold: 1.0,
}

2. 预测仅用于本地玩家

远程玩家应使用插值而非预测：

const identity = entity.getComponent(NetworkIdentity);

if (identity.bIsLocalPlayer) {
    // 使用预测系统
} else {
    // 使用 NetworkSyncSystem 的插值
}

3. 处理高延迟

// 高延迟网络增加缓冲
predictionConfig: {
    maxUnacknowledgedInputs: 120,  // 增加缓冲
    reconciliationSpeed: 5,        // 减慢校正速度
}

4. 确定性预测

确保客户端和服务器使用相同的物理计算：

// 使用固定时间步长
const FIXED_DT = 1 / 60;

function applyInput(state: PlayerState, input: PlayerInput): PlayerState {
    // 使用固定时间步长而非实际 deltaTime
    return {
        x: state.x + input.dx * MOVE_SPEED * FIXED_DT,
        y: state.y + input.dy * MOVE_SPEED * FIXED_DT,
        rotation: state.rotation,
    };
}

调试

// 获取预测系统实例
const predictionSystem = networkPlugin.predictionSystem;

if (predictionSystem) {
    console.log('Pending inputs:', predictionSystem.pendingInputCount);
    console.log('Current sequence:', predictionSystem.inputSequence);
}

---

定点数客户端预测（帧同步）

用于帧同步 (Lockstep) 的确定性客户端预测。

定点数基础知识请参考 定点数文档

基本用法

import {
    FixedClientPrediction,
    createFixedClientPrediction,
    type IFixedPredictor,
    type IFixedStatePositionExtractor
} from '@esengine/network';
import { Fixed32, FixedVector2 } from '@esengine/ecs-framework-math';

// 定义游戏状态
interface GameState {
    position: FixedVector2;
    velocity: FixedVector2;
}

// 实现预测器（必须使用定点数运算）
const predictor: IFixedPredictor<GameState, PlayerInput> = {
    predict(state: GameState, input: PlayerInput, deltaTime: Fixed32): GameState {
        const speed = Fixed32.from(100);
        const inputVec = FixedVector2.from(input.dx, input.dy);
        const velocity = inputVec.normalize().mul(speed);
        const displacement = velocity.mul(deltaTime);

        return {
            position: state.position.add(displacement),
            velocity
        };
    }
};

// 创建预测器
const prediction = createFixedClientPrediction(predictor, {
    maxUnacknowledgedInputs: 60,
    fixedDeltaTime: Fixed32.from(1 / 60),
    reconciliationThreshold: Fixed32.from(0.001),
    enableSmoothReconciliation: false  // 帧同步通常关闭
});

记录输入

function onUpdate(input: PlayerInput, currentState: GameState) {
    // 记录输入并获得预测状态
    const predicted = prediction.recordInput(input, currentState);

    // 渲染预测状态
    const pos = predicted.position.toObject();
    sprite.position.set(pos.x, pos.y);

    // 发送输入
    socket.send(JSON.stringify({
        frame: prediction.currentFrame,
        input
    }));
}

服务器校正

// 位置提取器
const posExtractor: IFixedStatePositionExtractor<GameState> = {
    getPosition(state: GameState): FixedVector2 {
        return state.position;
    }
};

// 收到服务器状态
function onServerState(serverState: GameState, serverFrame: number) {
    const reconciled = prediction.reconcile(
        serverState,
        serverFrame,
        posExtractor
    );
}

回滚重播

// 发现不同步时回滚
const correctedState = prediction.rollbackAndResimulate(
    serverFrame,
    authoritativeState
);

// 查看历史状态
const historicalState = prediction.getStateAtFrame(100);

预设移动预测器

import {
    createFixedMovementPredictor,
    createFixedMovementPositionExtractor,
    type IFixedMovementInput,
    type IFixedMovementState
} from '@esengine/network';

// 创建移动预测器（速度 100 单位/秒）
const movePredictor = createFixedMovementPredictor(Fixed32.from(100));
const posExtractor = createFixedMovementPositionExtractor();

const prediction = createFixedClientPrediction<IFixedMovementState, IFixedMovementInput>(
    movePredictor,
    { fixedDeltaTime: Fixed32.from(1 / 60) }
);

// 输入格式
const input: IFixedMovementInput = { dx: 1, dy: 0 };

API 导出

import {
    FixedClientPrediction,
    createFixedClientPrediction,
    createFixedMovementPredictor,
    createFixedMovementPositionExtractor,
    type IFixedInputSnapshot,
    type IFixedPredictedState,
    type IFixedPredictor,
    type IFixedStatePositionExtractor,
    type FixedClientPredictionConfig,
    type IFixedMovementInput,
    type IFixedMovementState
} from '@esengine/network';