---
description: 通用 GDScript 文件结构、命名、类型、注释与错误处理规范
globs: "**/*.gd"
alwaysApply: false
---

# GDScript 风格

## 文件结构

按 Godot 风格保持稳定顺序：`@tool`（如需）→ `class_name`（如需）→ `extends` → 文档注释 → signals → enums → constants → exports → public members → private members → lifecycle → public methods → private methods。

- 可复用类型使用 `class_name`；仅由 autoload 注册的脚本避免重复声明同名全局类。
- 缩进使用 Tab，单个文件内不得混用 Tab 与空格。
- 一个脚本聚焦一个主要职责；脚本持续膨胀时按状态、数据访问或表现职责拆分。

## 命名

- 文件、变量、函数、参数和信号使用 `snake_case`。
- 类名使用 `PascalCase`，常量使用 `UPPER_SNAKE_CASE`。
- 私有成员和私有方法使用 `_` 前缀；参数与成员冲突时使用 `p_` 前缀。
- 信号名称表达已经发生的事件，如 `entity_selected`，避免含糊的 `changed`。

## 类型与接口

- 函数参数和返回值显式标注类型；局部变量优先 `:=` 推断，容器尽量声明元素类型。
- 跨系统边界避免无结构的 `Dictionary`；可复用数据优先使用具名类型、Resource 或明确 schema。
- 可空值、失败返回和副作用必须从签名、名称或文档中可见。
- 只对已理解且范围最小的问题使用 `@warning_ignore`，不全局压制告警。

## 注释与诊断

- `##` 用于公开类型、属性和方法的文档；普通注释解释原因与约束，不复述代码。
- 日志和警告包含稳定的模块或类标签以及关键上下文。
- 可恢复的外部数据问题用明确错误信息处理；真正的内部不变量可用 `assert`，不要用断言处理正常用户输入。