Godot-Rust项目中Input单例在工具模式下的行为差异分析

问题背景

在Godot-Rust(gdext)项目开发过程中，开发者发现当使用#[class(tool)]注解时，Input和InputMap单例的行为与非工具模式存在显著差异。具体表现为在工具模式下无法正确获取项目自定义的输入动作，而只能访问编辑器内置的输入动作。

现象描述

在非工具模式下，以下代码能够正常工作：

let input_map = InputMap::singleton();
let actions = input_map.get_actions();
// 正确获取项目自定义输入动作

但当添加#[class(tool)]注解后：

#[derive(GodotClass)]
#[class(init, tool, base=Node)]
struct InputTest {
    base: Base<Node>,
}

同样的代码将只能获取到编辑器内置的输入动作（如"ui_left"等），而无法访问项目自定义的输入动作（如"move_left"等）。这会导致在工具模式下调用input.get_vector()等方法时出现"动作不存在"的错误提示。

技术原理

这种现象源于Godot引擎的设计机制：

1. 双单例模式：Godot引擎实际上维护着两套Input和InputMap单例实例 - 一套用于编辑器环境，另一套用于运行时游戏环境。

2. 工具脚本执行环境：当节点被标记为工具(tool)时，其代码不仅会在游戏运行时执行，也会在编辑器中执行。在编辑器环境下，访问的是编辑器自身的输入系统。

3. GDScript与GDExtension差异：值得注意的是，GDScript工具脚本能够正确获取项目输入设置，而GDExtension(包括Rust绑定)则表现出不同行为，这反映了底层实现的差异。

解决方案

开发者提供了几种可行的解决方案：

1. 编辑器环境检测

通过检查当前是否处于编辑器环境来避免在工具模式下处理输入：

if Engine::singleton().is_editor_hint() {
    return;
}
// 正常处理输入逻辑

这种方法简单有效，特别适合那些只需要在游戏运行时处理输入的场合。

2. 显式加载项目设置

对于需要在工具模式下访问项目输入设置的场景，可以显式加载项目设置：

InputMap.load_from_project_settings();

这种方法会强制从项目设置中重新加载输入映射，确保获取到的是项目自定义的输入动作。

最佳实践建议

1. 明确使用场景：在设计工具脚本时，应明确区分编辑器功能和游戏功能。编辑器功能通常应与游戏逻辑解耦。

2. 环境感知：任何可能受执行环境影响的功能都应添加环境检查，确保行为一致性。

3. 输入系统封装：考虑封装输入系统，在内部处理环境差异，为上层提供统一的接口。

4. 版本注意：值得注意的是，Godot 4.3对工具模式的处理有所改变，开发者应关注版本差异。

总结

Godot-Rust项目中Input单例在工具模式下的行为差异反映了引擎底层设计的特点。理解这种差异并采取适当的应对措施，是开发健壮的工具脚本的关键。通过环境检测或显式加载项目设置，开发者可以确保输入系统在各种环境下都能正常工作。