游戏客户端架构 / 系统课时
提炼三种引擎都能复用的接口
提炼三种引擎都能复用的接口
把 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 对象。
'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}`);
}预期输出
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 的记录和释放事件,验证旧跳跃不会补发;再把采集源换成读取同一数组的另一实现。若消费结果改变,先核对排序、状态清理与读取次数,而不是修改角色逻辑迁就适配器。