游戏客户端架构 / 系统课时

提炼三种引擎都能复用的接口

提炼三种引擎都能复用的接口

把 Unity、Unreal 和 Godot 的 API 换成同名函数,并不能保证输入行为一致。本课提炼采集源、输入核心与命令消费者三个接口,让引擎适配器提供普通记录,让玩法只接收有明确时序的动作,并用离线输入流验证契约。

学习目标

  • 用三个小接口隔离引擎事件、输入规则和玩法执行。
  • 规定逻辑帧、稳定顺序、消费确认与失焦清理的行为。
  • 使用同一纯逻辑核心处理实时适配器和录制输入源。

接口首先约定可观察行为

三种引擎可以共享字段与测试用例,不必共享同一种语言或内存对象。C#、C++ 和 GDScript 各自实现适配器,输出相同语义的数据;核心契约不能携带 InputAction、节点对象或引擎向量类型,避免上层再次依赖具体引擎。

接口 输入与输出 必须约定的行为
采集源 drain(tick) 返回普通记录 每帧只取一次,记录带帧内序号
输入核心 step(state, records) 返回新状态与命令 顺序确定,重复按下不变成新边沿
命令消费者 accept(command) 返回是否接受 同一命令最多接受一次,拒绝原因可记录

这是项目定义的契约,三个名称均不是引擎内置 API。采集源可以来自引擎回调,也可以来自录制文件。输入核心负责边沿、上下文和状态归约;消费者负责角色是否允许跳跃,不让输入核心查询角色组件。

把时序和所有权写进契约

记录按整数逻辑帧和帧内序号排序,禁止重复的排序键。多个线程或设备回调只能提交采集记录,统一入口在主线程分配最终序号;不能让不同线程各自从零计数,再依赖数组偶然的到达顺序解决冲突。

一次渲染更新与一次物理更新未必对应。适配器先保存短按边沿,装配层再把它交给确定的模拟帧。持续值写入该帧快照;不能让两个消费者各自调用一个会清空队列的读取函数,否则第二个消费者会漏输入。

本例规定菜单切换与失焦都会清理玩法状态及本批未交付命令;恢复焦点不补发旧按下。真实项目还须定义“已按住的键是否必须释放后才能再次生效”,并让所有适配器保持一致。设备断开可以按对应来源执行相同的取消策略。

用录制源运行完整接口协作

按以下步骤实现最小版本:先建立只读记录源,再实现无引擎依赖的状态归约器,最后接入带命令 id 的消费者。保存为 portable_input.js,执行 node portable_input.js。它验证项目契约,不创建假的 Unity、Unreal 或 Godot 对象。

js
'use strict';
const assert = require('node:assert/strict');

class RecordedSource {
  constructor(records) {
    const ids = new Set();
    this.records = records.map(record => {
      assert(Number.isInteger(record.tick) && record.tick >= 0);
      assert(Number.isInteger(record.seq) && record.seq >= 0);
      const id = `${record.tick}:${record.seq}`;
      assert(!ids.has(id), 'duplicate order');
      ids.add(id);
      return Object.freeze({ ...record });
    }).sort((a, b) => a.tick - b.tick || a.seq - b.seq);
    this.cursor = 0;
    this.previousTick = -1;
  }
  drain(tick) {
    assert.equal(tick, this.previousTick + 1, 'advance one tick at a time');
    this.previousTick = tick;
    const batch = [];
    while (this.records[this.cursor]?.tick === tick) {
      batch.push(this.records[this.cursor++]);
    }
    return Object.freeze(batch);
  }
}

function step(previous, records) {
  const state = { ...previous, held: new Set(previous.held) };
  const commands = [];
  for (const record of records) {
    if (record.kind === 'focus' || record.kind === 'context') {
      if (record.kind === 'focus') {
        assert.equal(typeof record.value, 'boolean');
        state.focused = record.value;
      } else {
        assert(['Gameplay', 'Menu'].includes(record.value));
        state.context = record.value;
      }
      // 状态边界取消旧意图;恢复后不合成历史按下。
      state.held.clear();
      commands.length = 0;
      continue;
    }
    assert.equal(record.kind, 'key');
    assert(['pressed', 'released'].includes(record.phase));
    if (record.phase === 'released') {
      state.held.delete(record.key);
      continue;
    }
    if (!state.focused || state.held.has(record.key)) continue;
    state.held.add(record.key);
    if (state.context === 'Gameplay' && record.key === 'Space') {
      commands.push({ id: `${record.tick}:${record.seq}`, action: 'Jump' });
    }
  }
  const move = state.focused && state.context === 'Gameplay'
    && state.held.has('KeyD') ? 1 : 0;
  return { state, move, commands };
}

class CommandSink {
  constructor() { this.accepted = new Set(); }
  accept(command) {
    if (command.action !== 'Jump' || this.accepted.has(command.id)) return false;
    this.accepted.add(command.id);
    return true;
  }
}

const source = new RecordedSource([
  { tick: 0, seq: 2, kind: 'key', key: 'Space', phase: 'pressed' },
  { tick: 0, seq: 1, kind: 'key', key: 'KeyD', phase: 'pressed' },
  { tick: 0, seq: 3, kind: 'key', key: 'Space', phase: 'pressed' },
  { tick: 1, seq: 1, kind: 'focus', value: false },
  { tick: 2, seq: 1, kind: 'focus', value: true },
  { tick: 2, seq: 2, kind: 'context', value: 'Menu' },
  { tick: 2, seq: 3, kind: 'key', key: 'Space', phase: 'pressed' }
]);
let state = { held: new Set(), focused: true, context: 'Gameplay' };
const sink = new CommandSink();
for (let tick = 0; tick < 3; tick++) {
  const result = step(state, source.drain(tick));
  state = result.state;
  const accepted = result.commands.filter(command => sink.accept(command)).length;
  for (const command of result.commands) assert.equal(sink.accept(command), false);
  const actions = result.commands.map(command => command.action).join(',') || '-';
  console.log(`tick=${tick} move=${result.move} commands=${actions} accepted=${accepted}`);
}

预期输出

text
tick=0 move=1 commands=Jump accepted=1
tick=1 move=0 commands=- accepted=0
tick=2 move=0 commands=- accepted=0

第零帧故意乱序,并重复报告按下;排序和 held 状态使跳跃只产生一次。第一帧失焦使移动归零,第二帧菜单阻断跳跃。消费者确认只证明命令被接受;实际跳跃成功仍需检查角色状态或执行回执。

示例命令 id 只包含帧与序号,去重集合仅用于这一次运行。生产 id 还应包含会话及玩家边界,避免场景重启后帧号归零发生碰撞;已确认且超出重放期限的帧可按窗口回收,或随明确的会话生命周期重建集合,不能无限保留历史 id。

扩展接口时保持边界清晰

示例把采集、映射和边沿约简为键盘按钮模型,没有实现轴死区、组合键或多玩家路由。添加这些能力时,应扩展普通记录与核心规则,而不是让核心读取引擎单例。多来源动作还需要按来源聚合,不能直接用此例的单键状态代替完整动作状态。

消费者拒绝是否重试,必须由缓冲策略决定。普通离散命令可以报告拒绝后结束;需要等待落地的跳跃则在有效期内保留,并在真正接受时删除。确认接口还要区分“接收排队”和“已应用”,避免网络派发成功被误当作角色执行成功。

练习:加入 Menu 返回 Gameplay 的记录和释放事件,验证旧跳跃不会补发;再把采集源换成读取同一数组的另一实现。若消费结果改变,先核对排序、状态清理与读取次数,而不是修改角色逻辑迁就适配器。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

提炼三种引擎都能复用的接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通