config：更新项目配置和文档

- 更新Godot项目配置，添加自动加载脚本 - 完善.gitignore文件，排除不必要的文件 - 更新README文档，添加项目介绍和使用说明 - 更新主场景配置，集成认证系统 - 添加开发规范文档和项目结构说明
2025-12-24 20:39:33 +08:00
parent 5b67771bbc
commit 370cffbdd8
10 changed files with 2112 additions and 91 deletions
--- a/docs/code_comment_guide.md
+++ b/docs/code_comment_guide.md
@@ -0,0 +1,433 @@
+# GDScript 代码注释规范
+
+本文档详细说明了 whaleTown 项目中 GDScript 代码的注释规范，旨在提高代码可读性和维护性。
+
+## 目录
+
+- [基本原则](#基本原则)
+- [文件头注释](#文件头注释)
+- [类和函数注释](#类和函数注释)
+- [变量注释](#变量注释)
+- [行内注释](#行内注释)
+- [特殊注释标记](#特殊注释标记)
+- [AI辅助注释指南](#ai辅助注释指南)
+
+## 基本原则
+
+### 注释的目的
+- **解释为什么**，而不是解释做什么
+- **提供上下文**，帮助理解代码意图
+- **记录重要决策**和设计考虑
+- **警告潜在问题**和注意事项
+
+### 注释质量标准
+- 简洁明了，避免冗余
+- 使用中文，保持一致性
+- 及时更新，与代码同步
+- 避免显而易见的注释
+
+## 文件头注释
+
+每个 GDScript 文件都应该包含文件头注释，说明文件的用途和基本信息。
+
+### 标准格式
+
+```gdscript
+# ============================================================================
+# 文件名: PlayerController.gd
+# 作用: 玩家角色控制器，处理玩家输入和移动逻辑
+# 
+# 主要功能:
+# - 处理键盘和手柄输入
+# - 控制角色移动和跳跃
+# - 管理角色状态切换
+# - 处理碰撞检测
+#
+# 依赖: MovementComponent, AnimationComponent
+# 作者: [开发者名称]
+# 创建时间: 2024-12-24
+# ============================================================================
+
+extends CharacterBody2D
+```
+
+### 管理器类文件头
+
+```gdscript
+# ============================================================================
+# 游戏管理器 - GameManager.gd
+# 
+# 全局单例管理器，负责游戏状态管理和生命周期控制
+# 
+# 核心职责:
+# - 游戏状态切换 (加载、认证、游戏中、暂停等)
+# - 用户信息管理
+# - 全局配置访问
+# - 系统初始化和清理
+#
+# 使用方式:
+#   GameManager.change_state(GameManager.GameState.IN_GAME)
+#   GameManager.set_current_user("player123")
+#
+# 注意事项:
+# - 作为自动加载单例，全局可访问
+# - 状态变更会触发 game_state_changed 信号
+# ============================================================================
+
+extends Node
+```
+## 类和函数注释
+
+### 类注释
+
+```gdscript
+# 玩家数据类
+# 
+# 存储和管理玩家的基本属性和状态信息
+# 支持数据序列化和反序列化，用于存档系统
+class_name PlayerData
+
+# 武器组件类
+# 
+# 为角色提供武器功能，包括攻击、换弹、特殊技能等
+# 可以挂载到任何具有攻击能力的角色上
+#
+# 使用示例:
+#   var weapon = WeaponComponent.new()
+#   weapon.setup_weapon("sword", 50)
+#   add_child(weapon)
+class_name WeaponComponent
+```
+
+### 函数注释格式
+
+```gdscript
+# 处理玩家输入并更新移动状态
+# 
+# 参数:
+#   delta: float - 帧时间间隔
+# 
+# 返回值: 无
+# 
+# 注意事项:
+# - 需要在 _physics_process 中调用
+# - 会自动处理重力和碰撞
+func handle_movement(delta: float) -> void:
+
+# 验证用户输入的邮箱格式
+# 
+# 参数:
+#   email: String - 待验证的邮箱地址
+# 
+# 返回值:
+#   Dictionary - 包含验证结果和错误信息
+#   {
+#     "valid": bool,      # 是否有效
+#     "message": String   # 错误信息（如果无效）
+#   }
+# 
+# 使用示例:
+#   var result = validate_email("test@example.com")
+#   if result.valid:
+#       print("邮箱格式正确")
+static func validate_email(email: String) -> Dictionary:
+```
+## 变量注释
+
+### 成员变量注释
+
+```gdscript
+# 玩家基础属性
+@export var max_health: int = 100        # 最大生命值
+@export var move_speed: float = 200.0    # 移动速度 (像素/秒)
+@export var jump_force: float = -400.0   # 跳跃力度 (负值向上)
+
+# 状态管理
+var current_health: int                  # 当前生命值
+var is_grounded: bool = false           # 是否在地面上
+var can_double_jump: bool = true        # 是否可以二段跳
+
+# 节点引用 - 在 _ready() 中初始化
+@onready var sprite: Sprite2D = $Sprite2D
+@onready var collision: CollisionShape2D = $CollisionShape2D
+@onready var animation_player: AnimationPlayer = $AnimationPlayer
+
+# 私有变量 - 内部使用
+var _velocity: Vector2 = Vector2.ZERO    # 当前速度向量
+var _last_direction: int = 1             # 最后面向方向 (1=右, -1=左)
+```
+
+### 常量注释
+
+```gdscript
+# 游戏配置常量
+const GRAVITY: float = 980.0             # 重力加速度 (像素/秒²)
+const MAX_FALL_SPEED: float = 1000.0     # 最大下落速度
+const COYOTE_TIME: float = 0.1           # 土狼时间 (离开平台后仍可跳跃的时间)
+
+# 输入动作名称
+const ACTION_MOVE_LEFT: String = "move_left"
+const ACTION_MOVE_RIGHT: String = "move_right"
+const ACTION_JUMP: String = "jump"
+
+# 动画名称常量
+const ANIM_IDLE: String = "idle"
+const ANIM_WALK: String = "walk"
+const ANIM_JUMP: String = "jump"
+const ANIM_FALL: String = "fall"
+```
+
+## 行内注释
+
+### 复杂逻辑注释
+
+```gdscript
+func update_movement(delta: float):
+    # 处理水平移动输入
+    var input_direction = Input.get_axis("move_left", "move_right")
+    
+    if input_direction != 0:
+        velocity.x = input_direction * move_speed
+        _last_direction = sign(input_direction)  # 记录面向方向
+    else:
+        # 应用摩擦力，逐渐停止
+        velocity.x = move_toward(velocity.x, 0, friction * delta)
+    
+    # 应用重力 (只在空中时)
+    if not is_on_floor():
+        velocity.y += gravity * delta
+        velocity.y = min(velocity.y, max_fall_speed)  # 限制最大下落速度
+    
+    # 处理跳跃输入
+    if Input.is_action_just_pressed("jump"):
+        if is_on_floor():
+            velocity.y = jump_force  # 普通跳跃
+        elif can_double_jump:
+            velocity.y = jump_force * 0.8  # 二段跳 (力度稍小)
+            can_double_jump = false
+    
+    # 重置二段跳能力
+    if is_on_floor() and not can_double_jump:
+        can_double_jump = true
+```
+
+### 临时解决方案注释
+
+```gdscript
+func handle_collision(body: Node2D):
+    # TODO: 重构碰撞处理逻辑，当前实现过于复杂
+    # FIXME: 在某些情况下会出现重复碰撞检测
+    # HACK: 临时解决方案，等待 Godot 4.6 修复相关 bug
+    
+    if body.has_method("take_damage"):
+        # NOTE: 伤害计算需要考虑护甲和抗性
+        var damage = calculate_damage(base_damage)
+        body.take_damage(damage)
+```
+## 特殊注释标记
+
+使用标准化的标记来标识不同类型的注释：
+
+### 标记类型
+
+```gdscript
+# TODO: 待实现的功能
+# TODO: 添加音效播放功能
+# TODO: 实现存档系统
+
+# FIXME: 需要修复的问题
+# FIXME: 内存泄漏问题，需要及时释放资源
+# FIXME: 在低帧率下移动不流畅
+
+# HACK: 临时解决方案
+# HACK: 绕过 Godot 引擎的已知 bug
+# HACK: 临时方案，等待更好的实现
+
+# NOTE: 重要说明
+# NOTE: 此函数会修改全局状态，谨慎使用
+# NOTE: 性能敏感代码，避免频繁调用
+
+# WARNING: 警告信息
+# WARNING: 不要在 _ready() 之前调用此函数
+# WARNING: 此操作不可逆，请确认后执行
+
+# OPTIMIZE: 性能优化点
+# OPTIMIZE: 可以使用对象池优化内存分配
+# OPTIMIZE: 考虑使用缓存提高查询效率
+```
+
+### 版本和兼容性标记
+
+```gdscript
+# @since 1.0.0 - 添加基础移动功能
+# @deprecated 使用 new_movement_system() 替代
+# @godot_version 4.5+ - 需要 Godot 4.5 或更高版本
+# @platform_specific Windows/Linux - 仅在桌面平台可用
+```
+
+## AI辅助注释指南
+
+### 为AI提供的注释模板
+
+当需要AI帮助补充注释时，请使用以下模板：
+
+```gdscript
+# [AI_COMMENT_REQUEST]
+# 请为以下函数添加详细注释，包括：
+# - 功能描述
+# - 参数说明
+# - 返回值说明
+# - 使用示例
+# - 注意事项
+func complex_function(param1: String, param2: int) -> Dictionary:
+    # 复杂的业务逻辑...
+    pass
+```
+
+### AI注释补充规则
+
+1. **保持一致性** - 遵循项目现有的注释风格
+2. **关注业务逻辑** - 重点解释业务含义，而非语法
+3. **提供上下文** - 说明函数在整个系统中的作用
+4. **标注复杂度** - 对复杂算法提供额外说明
+
+### 示例：AI补充前后对比
+
+**补充前：**
+```gdscript
+func calculate_damage(base_damage: int, armor: int, resistance: float) -> int:
+    var final_damage = base_damage
+    final_damage -= armor
+    final_damage *= (1.0 - resistance)
+    return max(1, final_damage)
+```
+
+**AI补充后：**
+```gdscript
+# 计算最终伤害值
+# 
+# 根据基础伤害、护甲值和抗性计算实际造成的伤害
+# 伤害计算公式: (基础伤害 - 护甲) × (1 - 抗性)
+# 
+# 参数:
+#   base_damage: int - 基础伤害值
+#   armor: int - 目标护甲值 (减少固定伤害)
+#   resistance: float - 目标抗性 (0.0-1.0, 减少百分比伤害)
+# 
+# 返回值:
+#   int - 最终伤害值 (最小为1，确保至少造成1点伤害)
+# 
+# 使用示例:
+#   var damage = calculate_damage(100, 20, 0.3)  # 结果: 56
+# 
+# 注意事项:
+# - 护甲为负值时会增加伤害
+# - 抗性超过1.0时可能导致负伤害，但会被限制为1
+func calculate_damage(base_damage: int, armor: int, resistance: float) -> int:
+    var final_damage = base_damage
+    final_damage -= armor                    # 减去护甲值
+    final_damage *= (1.0 - resistance)      # 应用抗性
+    return max(1, final_damage)             # 确保最小伤害为1
+```
+## 注释最佳实践
+
+### 什么时候需要注释
+
+**必须添加注释的情况：**
+- 复杂的算法和业务逻辑
+- 非显而易见的设计决策
+- 临时解决方案和已知问题
+- 公共API和接口函数
+- 性能敏感的代码段
+- 平台特定或版本特定的代码
+
+**不需要注释的情况：**
+- 显而易见的代码 (`var count = 0  # 计数器` ❌)
+- 重复函数名的注释 (`func get_name() -> String: # 获取名称` ❌)
+- 过时或错误的注释
+
+### 注释维护原则
+
+```gdscript
+# ✅ 好的注释 - 解释为什么这样做
+# 使用二分查找提高大数组的查询效率
+# 当数组长度超过100时，线性查找性能会显著下降
+func binary_search(array: Array, target: Variant) -> int:
+
+# ❌ 坏的注释 - 重复代码内容
+# 遍历数组查找目标值
+func linear_search(array: Array, target: Variant) -> int:
+```
+
+### 团队协作注释
+
+```gdscript
+# 多人协作时的注释规范
+class_name NetworkManager
+
+# @author: 张三 - 网络连接模块
+# @author: 李四 - 数据同步模块
+# @reviewer: 王五 - 代码审查
+# @last_modified: 2024-12-24
+
+# 网络连接状态枚举
+# 
+# 定义了客户端与服务器的连接状态
+# 状态转换: DISCONNECTED -> CONNECTING -> CONNECTED -> DISCONNECTED
+enum ConnectionState {
+    DISCONNECTED,    # 未连接
+    CONNECTING,      # 连接中
+    CONNECTED,       # 已连接
+    RECONNECTING     # 重连中 - @added by 李四 2024-12-20
+}
+```
+
+## 注释检查清单
+
+在提交代码前，请检查以下项目：
+
+### 文件级别检查
+- [ ] 文件头注释完整（文件名、作用、主要功能）
+- [ ] 依赖关系说明清楚
+- [ ] 作者和创建时间已填写
+
+### 函数级别检查
+- [ ] 公共函数有完整的参数和返回值说明
+- [ ] 复杂函数有使用示例
+- [ ] 特殊情况和注意事项已标注
+
+### 代码级别检查
+- [ ] 复杂逻辑有行内注释说明
+- [ ] 魔法数字有常量定义和注释
+- [ ] TODO/FIXME 标记有明确的处理计划
+
+### 质量检查
+- [ ] 注释内容准确，与代码一致
+- [ ] 中文表达清晰，无错别字
+- [ ] 注释格式符合项目规范
+
+## 注释工具和插件
+
+### Godot编辑器设置
+```
+# 在 Godot 编辑器中设置注释快捷键
+# 编辑器设置 -> 快捷键 -> 注释/取消注释: Ctrl+/
+```
+
+### 推荐的注释插件
+- **GDScript Language Server** - 提供注释语法高亮
+- **Code Formatter** - 自动格式化注释
+- **Documentation Generator** - 自动生成API文档
+
+---
+
+## 总结
+
+良好的注释是代码质量的重要组成部分。遵循本规范可以：
+
+1. **提高代码可读性** - 帮助团队成员快速理解代码
+2. **降低维护成本** - 减少后期修改和调试时间
+3. **促进知识传承** - 保留设计思路和业务逻辑
+4. **支持AI辅助开发** - 为AI提供更好的上下文信息
+
+记住：**好的注释解释为什么，而不是做什么。**