按键位置、布局与字符：Godot 3.4的键盘事件分了哪些层

说“按了同一个键”，可能是在指键盘上的同一位置，也可能是在指当前布局里的同一按键，还可能是在指输入了相同字符。Godot 3.4的InputEventKey文档把这些信息分别放入不同属性。阅读旧项目资料时，保留字段原名与版本，才能知道描述究竟落在哪个层次。

physical_scancode代表101或102键美式QWERTY键盘上的物理位置。它使用KeyList中的常量，但定义关心的是位置。这里的物理位置含义，不应悄悄改成当前键盘布局解释出来的键值；否则，原本用来区分的条件就在转述中消失了。

scancode同样对应KeyList常量，却被定义为当前键盘布局中的键。两个属性的名称相近、数值类型也相同，并不意味着文档把它们当作同一信息。一个以美式QWERTY位置为参照，另一个以当前布局为参照；如果记录只写“扫描码”，读者仍不知道采用的是哪一个。

unicode则在适用时记录键的Unicode标识。这一项讨论字符层面，而且有明确限制：组合字符及复杂书写系统的标识，若没有启用IME输入模式，可能不可用。因此，收到键盘事件不能自动推导出已经得到完整文本字符。文档中的“适用时”不是可有可无的修饰。

这份类型说明还把按下、释放与echo事件并列。pressed为真表示键处于按下状态，为假表示释放；echo为真则表示在这次事件之前，该键已经被按下，用户正在保持按住。前者描述本次状态，后者说明与此前按下有关的持续条件，两者不是给同一事实重复取名。

例如，一份事件记录若只留下pressed为真，能够表达按下状态，却没有同时交代是否属于保持按住所形成的echo。这个例子只是按字段定义作出的资料解读，不是实际运行生成的事件样本。把状态与事件延续条件分开，才不会用一个布尔值替另一个补出未经记录的信息。

方法部分延续同样的区分：一个方法返回带修饰键的physical_scancode，另一个返回带修饰键的scancode，说明中以Shift或Alt为例。加入修饰键信息之后，底层是位置还是当前布局的差别仍然存在；组合了更多信息，并不让两个方法的含义自动合并。

本文依据3.4历史版文档的描述、属性与方法说明，没有给出代码、IME启用步骤或当前版本迁移方案，也没有把字段改名为较新版本的名称。对游戏开发资料来说，物理位置、布局解释、字符标识、按下状态与持续事件分别表达什么，正是准确理解这份旧接口说明的基础。