游戏客户端架构 / 系统课时
规划输入模块的代码与配置目录
规划输入模块的代码与配置目录
输入系统能工作后,常见的新问题是默认键位、玩家改键、引擎脚本和测试夹具混在一起,修一个平台就影响其他平台。本课按依赖与数据所有权规划目录,并给出可执行的边界检查,使目录划分能够约束代码,而不只是整理文件。
学习目标
- 分开输入契约、纯逻辑核心、引擎适配和启动装配。
- 为默认配置、玩家覆盖与测试夹具确定独立归属。
- 检查非法依赖和循环依赖,防止目录边界被逐步侵蚀。
目录由依赖方向决定
先写清楚谁可以依赖谁,再决定文件放在哪里。契约描述普通记录与动作值;核心实现映射、Context、缓冲;适配层把引擎事件转换为契约记录。运行时入口负责创建对象并连接接口,核心不能为了方便反过来创建 Godot 节点或读取 Unity 单例。
以下是一个项目的建议布局,不是任何引擎要求的固定目录。具体扩展名按语言调整,职责保持不变;不要为了对称而提前创建尚未使用的平台实现。
| 目录 | 保存内容 | 边界 |
|---|---|---|
input/contracts/ |
事件、动作、消费者接口 | 不依赖核心或引擎 |
input/core/ |
映射、Context、状态、缓冲 | 只使用契约和纯逻辑 |
input/adapters/ |
当前平台的引擎接入 | 使用契约,不操作角色 |
input/config/ |
配置解析、版本迁移、校验 | 不读取引擎输入状态 |
input/diagnostics/ |
追踪格式、指标输出 | 通过接口接收证据 |
input/runtime/ |
对象创建、绑定和生命周期 | 唯一负责装配的入口 |
input/data/ |
默认动作和平台配置 | 版本控制中的只读数据 |
tests/input/ |
确定性夹具、边界测试 | 不进入正式输入采集路径 |
“核心只使用纯逻辑”不意味着所有模块都必须是静态函数。它可以持有缓冲和状态,只要时间、配置与事件由外部传入。诊断写盘或上传也应留在外围,通过接口获取信息,不能让高频核心路径直接访问磁盘。
配置与运行状态分开保存
系统默认和平台默认随版本发布,玩家覆盖写入应用可写的用户目录。玩家文件只保存稳定 binding id 对应的修改项,并带 schemaVersion;不要把用户机器的绝对路径写进默认配置,也不要把当前 held 状态序列化成玩家设置。
加载顺序是读取系统默认、叠加平台差异、叠加玩家覆盖,最后校验完整有效配置。它们的优先级由加载器明确规定,不由目录遍历顺序决定。删除某个默认动作时,要同步迁移旧覆盖项,不能默默创建一个核心不认识的新动作。
按以下步骤落地:先建立契约与一个真实适配器,把现有核心迁入独立目录;再分离配置数据与加载器,由启动入口一次装配;最后添加依赖检查和输入夹具。配置热重载也从装配入口切换,在明确的帧边界清理旧状态并发布新版本。
用完整例程检查模块边界
保存下面的代码为 input_layout_check.js,执行 node input_layout_check.js。清单中的名字表示本项目规划的模块 id;程序检查这些普通数据,不读取或伪造 Godot 等引擎模块。正式项目可从构建工具提取实际 import,再复用同样规则。
'use strict';
const assert = require('node:assert/strict');
const permitted = {
contracts: new Set(['contracts']),
core: new Set(['contracts', 'core']),
adapters: new Set(['contracts']),
config: new Set(['contracts']),
diagnostics: new Set(['contracts']),
runtime: new Set(['contracts', 'core', 'adapters', 'config', 'diagnostics'])
};
function validateLayout(modules) {
const names = Object.keys(modules);
for (const name of names) {
const layer = name.split('/')[0];
if (!permitted[layer]) throw new Error(`UNKNOWN_LAYER ${name}`);
for (const target of modules[name]) {
if (!Object.hasOwn(modules, target)) throw new Error(`UNKNOWN_MODULE ${target}`);
if (!permitted[layer].has(target.split('/')[0])) {
throw new Error(`FORBIDDEN_DEPENDENCY ${name} -> ${target}`);
}
}
}
const complete = new Set(), stack = [];
function visit(name) {
if (complete.has(name)) return;
const index = stack.indexOf(name);
if (index !== -1) {
throw new Error(`CYCLE ${[...stack.slice(index), name].join(' -> ')}`);
}
// 当前路径检测循环;已完成集合避免重复扫描共享依赖。
stack.push(name);
for (const target of modules[name]) visit(target);
stack.pop();
complete.add(name);
}
for (const name of names) visit(name);
return names.length;
}
const layout = {
'contracts/types': [],
'core/buffer': ['contracts/types'],
'core/router': ['contracts/types', 'core/buffer'],
'adapters/godot': ['contracts/types'],
'config/loader': ['contracts/types'],
'diagnostics/trace': ['contracts/types'],
'runtime/bootstrap': ['core/router', 'adapters/godot', 'config/loader', 'diagnostics/trace']
};
console.log(`valid layout: ${validateLayout(layout)} modules`);
function expectRejection(modules, message) {
assert.throws(() => validateLayout(modules), error => {
assert.equal(error.message, message);
console.log(`rejected: ${error.message}`);
return true;
});
}
const illegal = JSON.parse(JSON.stringify(layout));
illegal['core/router'].push('adapters/godot');
expectRejection(illegal, 'FORBIDDEN_DEPENDENCY core/router -> adapters/godot');
const cyclic = JSON.parse(JSON.stringify(layout));
cyclic['core/buffer'].push('core/router');
expectRejection(cyclic, 'CYCLE core/buffer -> core/router -> core/buffer');预期输出
valid layout: 7 modules
rejected: FORBIDDEN_DEPENDENCY core/router -> adapters/godot
rejected: CYCLE core/buffer -> core/router -> core/buffer第一个反例展示“文件放在 core 目录,内部却导入引擎适配器”的失败;第二个反例说明同层模块也不能循环依赖。runtime/bootstrap 同时认识核心与适配器是合理的,因为创建与连接对象正是它的职责。
把目录检查纳入维护流程
只对手写清单运行此例,不能证明真实源代码遵守边界。正式检查必须覆盖实际依赖,包括动态加载、全局服务定位器和生成文件;否则核心通过全局对象访问设备,仍能绕过静态 import 检查。外部引擎依赖应只在适配层白名单中出现。
每个目录还要有明确生命周期:场景装配时注册一次采集回调,销毁时解除订阅;配置重载替换版本,不再追加第二套监听。把设备监听分散到角色目录,容易在场景切换后留下重复输入源,这类错误仅靠目录命名发现不了。
练习:把项目中一个直接读设备的角色函数迁移到适配器,由装配入口注入契约接口;再列出默认配置、玩家覆盖与回放夹具的存储位置。验收时同时检查依赖方向、用户数据保存位置和重复订阅计数,三项都成立,目录划分才真正减少后续维护成本。