在godot-nim/gdext-nim项目中实现Nim变量对GDScript可见但不暴露给编辑器

在godot-nim/gdext-nim项目中实现Nim变量对GDScript可见但不暴露给编辑器

gdext-nim Nim for Godot GDExtension. A pure library and a CLI tool. 项目地址: https://gitcode.com/gh_mirrors/gd/gdext-nim

在Godot游戏引擎中使用Nim语言开发时，我们经常需要让Nim类中的变量能够被GDScript访问，但又不希望这些变量出现在Godot编辑器的属性面板中。本文将详细介绍如何通过gdext-nim项目实现这一需求。

问题背景

当我们在Nim中定义一个继承自Node的类时，通常会这样写：

type myClass* = ptr object of Node
    target*: Node

默认情况下，这样的变量定义虽然可以在Nim代码中访问，但无法直接从GDScript中访问。如果使用{.gdexport.}注解：

type myClass* = ptr object of Node
    target* {.gdexport.}: Node

虽然可以让GDScript访问该变量，但同时也会将该变量暴露在Godot编辑器的属性面板中，这可能不是我们想要的效果。

解决方案

gdext-nim项目提供了gdexport_storage注解，完美解决了这个问题。这个注解相当于GDScript中的@export_storage注解，它允许变量被GDScript访问，但不会显示在编辑器中。

type myClass* = ptr object of Node
    target* {.gdexport_storage.}: Node

技术细节

1. 变量可见性控制：

   • 无注解：仅Nim代码可见
   • gdexport：Nim和GDScript可见，且显示在编辑器
   • gdexport_storage：Nim和GDScript可见，但不显示在编辑器

2. 使用场景：

   • 需要在运行时动态修改但不希望用户通过编辑器修改的变量
   • 需要GDScript访问但不希望暴露给设计人员的内部变量
   • 需要保持代码整洁，避免编辑器属性面板过于杂乱

3. 注意事项：

   • 使用gdexport_storage注解的变量仍然需要遵循Godot的变量命名规范
   • 这些变量在GDScript中访问时与普通导出的变量访问方式完全相同
   • 适用于所有Godot支持的基本类型和自定义类型

实际应用示例

假设我们有一个敌人AI类，需要让GDScript设置目标但不希望设计人员随意修改：

type EnemyAI* = ptr object of Node
    # 只能在代码中设置的目标
    target* {.gdexport_storage.}: Node
    # 设计人员可以调整的警戒范围
    alertRange* {.gdexport.}: float = 10.0

在GDScript中：

var enemy = $EnemyAI
enemy.target = $Player  # 可以设置
print(enemy.target)     # 可以读取

总结

gdext-nim项目提供的gdexport_storage注解为Nim和GDScript之间的交互提供了更精细的控制能力。通过合理使用这个特性，开发者可以更好地组织代码结构，保护关键变量不被随意修改，同时保持脚本系统间的必要通信能力。这种设计既保证了开发效率，又提高了代码的安全性和可维护性。

gdext-nim Nim for Godot GDExtension. A pure library and a CLI tool. 项目地址: https://gitcode.com/gh_mirrors/gd/gdext-nim