godot-gdscript-mastery

GDScript 精通指南

编写高性能、易维护 GDScript 的专家指导——聚焦 Godot 中的陷阱决策树，而非重述风格指南。

不要加载

• 不要为一般性行文风格或 Godot 引擎版本升级（3→4 / 4.x 跨版本升级）加载此技能——相关内容请参阅 godot-version-migration（以及该页面汇总的官方升级指南）。
• 不要预先加载下面的所有脚本；只打开你正在实施的核心指令所需的必读脚本。
• 不要将 EditorScript 工具（type_checker、performance_analyzer、signal_architecture_validator）当作运行时游戏代码。

GDScript 中绝对不要做的事

• 绝对不要在同一个变量上同时使用 @onready 和 @export——初始化顺序会导致 @onready 覆盖检查器中的值。
• 绝对不要在遍历 Dictionary 时修改其大小——使用 dict.keys().duplicate()，或遍历副本，以安全地删除元素。
• 绝对不要使用基于字符串的 connect("signal", ...)——始终使用 Signal 对象语法（button.pressed.connect(...)），以确保编译时安全。
• 绝对不要尝试重写非虚拟的原生引擎方法——重写 queue_free() 或 get_class() 不受支持，且会被引擎回调忽略。
• 绝对不要在 _process() 中使用动态 get_node() 或 $——每帧查找路径都会拖慢 CPU。请缓存节点并使用 @onready。
• 绝对不要调用 Parent.method()——这违反了“信号向上，调用向下”的原则。请使用信号与父节点通信。
• 绝对不要使用 is 后接强制类型转换——如果类型检查通过后对象发生变化，程序就会崩溃。请使用 as 并检查是否为 null。
• 绝对不要使用 print() 进行生产环境调试——请使用 push_error()、push_warning() 或断点。
• 绝对不要在 _ready() 中预加载大型资源——请使用 ResourceLoader.load_threaded_request() 异步加载。
• 静态变量足够时，绝对不要在 Autoload 中使用全局变量——静态变量提供更好的封装性。

---

核心指令（决策树 + 必读脚本）

1. 强类型与性能

陷阱	决策
热路径中仍有 Variant？	为变量和返回值添加类型注解；优先使用类型化集合
在 _process 中进行通用数学运算？	使用类型化辅助函数（absf、ceili、clampf）
缺少绿色安全行？	使用 := 或显式类型修正类型推断

必读：typed_collections_mastery.gd、array_preallocation_perf.gd、type_checker.gd（EditorScript 审计）。

2. 信号架构

陷阱	决策
子节点需要父节点响应？	向上发出信号——绝不调用父节点的方法
跨脚本载荷不安全？	使用类型化 signal name(arg: Type)
信号连接是否清晰可见？	优先在 _ready() 中连接，而不是使用不可见的纯编辑器连线

必读：typed_signal_definitions.gd、signal_architecture_validator.gd。

3. 节点访问与生命周期安全

陷阱	决策
需要子节点？	使用 @onready / %UniqueName——绝不在 _init() 中使用
场景实例化的节点需要构造函数参数？	使用 @export 注入——_init(args) 会导致 PackedScene.instantiate() 失效
每帧都查找路径？	缓存一次；绝不在 _process 中使用 $ / get_node

必读：safe_type_casting.gd。

4. Callable 与信号（一级功能）

易踩的坑	决策
在回调中添加额外上下文？	Callable.bind(...)
丢弃未使用的信号参数？	Callable.unbind(n)
一次性超时逻辑？	可以使用内联 lambda；若需要像 create_callback 那样保持长期有效，请保留引用

MANDATORY：callable_binding_context.gd、unbind_signal_args.gd、advanced_lambdas.gd、functional_lambda_logic.gd。

5. 异步、静态变量与安全集合

易踩的坑	决策
不使用线程按顺序执行计时器？	使用 await 链——参见 await 管理器
不增加 Autoload 负担来管理全局状态？	使用 static var（完成后将大型静态变量置为 null）
遍历 Dictionary 时删除元素？	先克隆键

MANDATORY：await_sequence_manager.gd、static_var_singleton_alt.gd、dictionary_safe_iteration.gd、performance_analyzer.gd（EditorScript）。

脚本目录（全部文件）

脚本	何时查看
typed_collections_mastery.gd	Typed Array/Dictionary 操作码
functional_lambda_logic.gd	reduce / all / any
advanced_lambdas.gd	高阶 Callable
safe_type_casting.gd	as + null 检查
typed_signal_definitions.gd	类型化信号边界
callable_binding_context.gd	bind() 上下文注入
unbind_signal_args.gd	unbind() 参数个数裁剪
await_sequence_manager.gd	非阻塞 await 流程
array_preallocation_perf.gd	resize() 预分配
static_var_singleton_alt.gd	轻量级全局状态
dictionary_safe_iteration.gd	安全地在遍历时删除元素
type_checker.gd	EditorScript 类型审查
performance_analyzer.gd	EditorScript 热路径扫描
signal_architecture_validator.gd	EditorScript 信号向上检查

常见易踩的坑

• 不确定键是否存在时，优先使用 dict.get("key", default)，而不是 dict["key"]。
• 对关键 UI/节点，启用 Access as Scene Unique Name，并通过 %Name 读取。
• 脚本布局顺序：extends → class_name → 信号/枚举/常量 → 导出变量/onready → 生命周期 → 公共成员 → _private。

专家知识（按需加载）

**大模型无知规则：**如果通用 Agent 在阅读前并不了解某项知识，就加载参考资料——绝不要删除专家增量知识。

• gdscript-core-directives.md — 恢复基础教学内容（架构、原因、实现深度）

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接；转向同领域内容时加载相关技能——不要预先加载整个知识网络。

官方文档

• GDScript 基础 — 该技能规范的语言核心内容，包括类型化变量/函数、signal 声明、await 和一等 Callable。
• GDScript 风格指南 — 评审和重构中使用的规范脚本顺序（extends → class_name → 信号 → 导出变量 → 生命周期 → 方法）。
• GDScript 静态类型 — 说明类型化 Array/Dictionary 和返回类型为何能启用优化后的操作码和编辑器安全行。
• GDScript：动态语言简介 — 介绍 filter/map/reduce 辅助函数背后的 Lambda、高阶 Callable 和高级模式。
• GDScript 警告系统 — 将不安全的类型转换、未使用的信号和未类型化的热点路径转化为 CI 可见的警告。
• 逻辑偏好 — 介绍何时优先使用声明式信号而非命令式调用，以保持脚本的低耦合。
• 场景组织 — 本技能强制遵循的官方“信号向上、调用向下”所有权规则。
• 使用信号 — 介绍连接/发射模型，以及避免基于字符串按名称连接的原因。
• Callable — 用于注入或丢弃回调参数的 bind() / unbind() API，无需包装节点。
• Array — 脚本中使用的类型化数组、resize() 和函数式方法（filter/map/reduce/all/any）。
• Dictionary — 安全的 .get() 默认值，以及迭代键时不得更改大小的原因。
• CPU 优化 — 在 _process 循环中缓存 @onready / %UniqueName，而不是使用 get_node/$。

相关技能

前置条件

• godot-project-foundations — 项目布局、Autoload 注册和场景所有权约定，为类型化 GDScript 脚本提供基础。
• godot-composition — 组件边界明确了哪些脚本负责信号，哪些提供向下调用 API，为执行风格规范做好准备。

补充

• godot-version-migration — 引擎版本升级（3→4 语言变更、4.x 版本迁移）；本技能沿用当前的 GDScript 2.0 惯用写法。
• godot-signal-architecture — 在本技能介绍的类型化信号和 Callable 基础上，深入讲解连接标志、总线和序列器。
• godot-autoload-architecture — 对比重量级 Autoload 与此处展示的 static var 单例替代方案。
• godot-resource-data-patterns — 共享配置优先使用 Resources；围绕 Resource 负载保持 GDScript 模块精简且类型明确。
• godot-scene-management — 场景切换和加载器必须确保 @onready、唯一名称和 await 序列依然有效。
• godot-testing-patterns — 类型化信号和 Callables 可让单元测试中的 watch_signals / 间谍可靠运行。
• godot-debugging-profiling — 热路径仍然缓慢时，将本技能中的风格/性能问题与分析器和自定义监视器结合使用。
• godot-state-machine-advanced — FSM 的进入/退出处理程序应遵循相同的类型化信号和 await 序列约定。

下游 / 使用方

• godot-performance-optimization — 仅靠类型化 GDScript 不够时，可进一步采用此处的方案；服务、对象池以及更全面的 CPU/GPU 优化策略均在其中。
• godot-auditor — 项目范围的审计会采用本技能中明确规定的类型规则、信号向上传递规则和热路径规则。
• godot-ability-system — 能力系统需要类型化信号负载和可安全 await 的冷却机制，这些都建立在此处介绍的语言模式之上。
• godot-combat-system — 伤害/死亡事件的扇出依赖此处介绍的类型化发射和安全转换。

主索引

• godot-master — 库路由器和镜像模块入口；需要查明哪个 Domain Skill 负责处理跨领域脚本问题时，请打开此项。