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

规划输入模块的代码与配置目录

规划输入模块的代码与配置目录

输入系统能工作后,常见的新问题是默认键位、玩家改键、引擎脚本和测试夹具混在一起,修一个平台就影响其他平台。本课按依赖与数据所有权规划目录,并给出可执行的边界检查,使目录划分能够约束代码,而不只是整理文件。

学习目标

  • 分开输入契约、纯逻辑核心、引擎适配和启动装配。
  • 为默认配置、玩家覆盖与测试夹具确定独立归属。
  • 检查非法依赖和循环依赖,防止目录边界被逐步侵蚀。

目录由依赖方向决定

先写清楚谁可以依赖谁,再决定文件放在哪里。契约描述普通记录与动作值;核心实现映射、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,再复用同样规则。

js
'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');

预期输出

text
valid layout: 7 modules
rejected: FORBIDDEN_DEPENDENCY core/router -> adapters/godot
rejected: CYCLE core/buffer -> core/router -> core/buffer

第一个反例展示“文件放在 core 目录,内部却导入引擎适配器”的失败;第二个反例说明同层模块也不能循环依赖。runtime/bootstrap 同时认识核心与适配器是合理的,因为创建与连接对象正是它的职责。

把目录检查纳入维护流程

只对手写清单运行此例,不能证明真实源代码遵守边界。正式检查必须覆盖实际依赖,包括动态加载、全局服务定位器和生成文件;否则核心通过全局对象访问设备,仍能绕过静态 import 检查。外部引擎依赖应只在适配层白名单中出现。

每个目录还要有明确生命周期:场景装配时注册一次采集回调,销毁时解除订阅;配置重载替换版本,不再追加第二套监听。把设备监听分散到角色目录,容易在场景切换后留下重复输入源,这类错误仅靠目录命名发现不了。

练习:把项目中一个直接读设备的角色函数迁移到适配器,由装配入口注入契约接口;再列出默认配置、玩家覆盖与回放夹具的存储位置。验收时同时检查依赖方向、用户数据保存位置和重复订阅计数,三项都成立,目录划分才真正减少后续维护成本。

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

目录与阅读设置

阅读设置

17

记录一个想法

规划输入模块的代码与配置目录

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

登录哪都通