forked from datawhale/whale-town-front
docs：创建git提交指导文档与命名规则指导文档，更新readme内容
This commit is contained in:
49
README.md
49
README.md
@@ -43,6 +43,55 @@ whaleTown/
|
||||
- **资源文件**: 图片、音频等资源存放在 `assets/` 目录
|
||||
- **游戏数据**: 配置文件、关卡数据等存放在 `data/` 目录
|
||||
|
||||
### 命名规范
|
||||
|
||||
本项目遵循统一的命名规范以保持代码一致性：
|
||||
|
||||
**核心规则**：
|
||||
|
||||
- **场景文件**：`下划线_scene.tscn` 或 `下划线_prefab.tscn`
|
||||
- 示例：`main_scene.tscn`、`player_prefab.tscn`
|
||||
- **脚本文件**：`PascalCase.gd`（大驼峰）
|
||||
- 示例：`PlayerController.gd`、`UI_MainMenu.gd`
|
||||
- **节点名称**：`camelCase`（小驼峰）
|
||||
- 示例：`playerHpBar`、`startButton`
|
||||
- **变量/函数**：`camelCase`（小驼峰）
|
||||
- 示例：`var moveSpeed`、`func getPlayerPos()`
|
||||
- **常量**：`UPPER_CASE`（全大写 + 下划线）
|
||||
- 示例：`const MAX_HEALTH = 100`
|
||||
- **资源文件**：`lower_case`（小写 + 下划线）
|
||||
- 示例：`bg_main_menu.png`、`sound_jump.wav`
|
||||
|
||||
📖 查看完整的 [命名规范文档](docs/naming_convention.md)
|
||||
|
||||
### Git 提交规范
|
||||
|
||||
本项目遵循统一的 Git 提交信息格式：`<类型>：<描述>`
|
||||
|
||||
**常用提交类型**：
|
||||
|
||||
- `init`：项目初始化
|
||||
- `feat`：新增功能
|
||||
- `fix`：修复 Bug
|
||||
- `docs`：文档更新
|
||||
- `scene`：场景文件相关
|
||||
- `asset`：资源文件相关
|
||||
- `ui`：UI 界面相关
|
||||
- `gameplay`：游戏玩法相关
|
||||
- `refactor`：代码重构
|
||||
- `perf`：性能优化
|
||||
|
||||
**提交示例**：
|
||||
|
||||
```bash
|
||||
git commit -m "init：项目初始化，搭建Godot文件结构"
|
||||
git commit -m "feat：实现玩家角色的移动和跳跃"
|
||||
git commit -m "fix：修复敌人穿墙的碰撞问题"
|
||||
git commit -m "scene：创建战斗场景并配置相机"
|
||||
```
|
||||
|
||||
📖 查看完整的 [Git 提交规范文档](docs/git_commit_guide.md)
|
||||
|
||||
## 贡献
|
||||
|
||||
欢迎提交 Issue 和 Pull Request！
|
||||
|
||||
157
docs/git_commit_guide.md
Normal file
157
docs/git_commit_guide.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# Git 提交规范
|
||||
|
||||
本文档定义了项目的 Git 提交信息格式规范，以保持提交历史的清晰和一致性。
|
||||
|
||||
## 提交格式
|
||||
|
||||
```
|
||||
<类型>：<简短描述>
|
||||
|
||||
[可选的详细描述]
|
||||
|
||||
[可选的注释或关联 Issue]
|
||||
```
|
||||
|
||||
## 提交类型
|
||||
|
||||
### 主要类型
|
||||
|
||||
| 类型 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `init` | 项目初始化 | `init：项目初始化，搭建Godot文件结构` |
|
||||
| `feat` | 新增功能 | `feat：添加角色移动系统` |
|
||||
| `fix` | 修复 Bug | `fix：修复角色跳跃时的碰撞检测问题` |
|
||||
| `docs` | 文档更新 | `docs：更新 README 中的安装说明` |
|
||||
| `style` | 代码格式调整（不影响功能） | `style：统一代码缩进格式` |
|
||||
| `refactor` | 代码重构（不新增功能也不修复 Bug） | `refactor：重构敌人 AI 逻辑` |
|
||||
| `perf` | 性能优化 | `perf：优化场景加载速度` |
|
||||
| `test` | 添加或修改测试 | `test：添加角色控制器单元测试` |
|
||||
| `chore` | 构建过程或辅助工具的变动 | `chore：更新 .gitignore 文件` |
|
||||
| `revert` | 回滚之前的提交 | `revert：回滚 feat：添加角色移动系统` |
|
||||
|
||||
### 场景和资源相关
|
||||
|
||||
| 类型 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `scene` | 场景文件相关 | `scene：创建主菜单场景` |
|
||||
| `asset` | 资源文件相关 | `asset：添加角色精灵图和动画` |
|
||||
| `ui` | UI 界面相关 | `ui：设计游戏暂停菜单` |
|
||||
| `audio` | 音频相关 | `audio：添加背景音乐和音效` |
|
||||
|
||||
### 游戏开发特定类型
|
||||
|
||||
| 类型 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `gameplay` | 游戏玩法相关 | `gameplay：实现敌人生成机制` |
|
||||
| `level` | 关卡设计相关 | `level：完成第一关卡设计` |
|
||||
| `config` | 配置文件相关 | `config：调整游戏难度参数` |
|
||||
| `plugin` | 插件相关 | `plugin：集成对话系统插件` |
|
||||
|
||||
## 提交示例
|
||||
|
||||
### 基础示例
|
||||
|
||||
```bash
|
||||
# 项目初始化
|
||||
git commit -m "init：项目初始化，搭建Godot文件结构"
|
||||
|
||||
# 新增功能
|
||||
git commit -m "feat：实现玩家角色的移动和跳跃"
|
||||
|
||||
# 修复问题
|
||||
git commit -m "fix：修复敌人穿墙的碰撞问题"
|
||||
|
||||
# 文档更新
|
||||
git commit -m "docs：添加 Git 提交规范文档"
|
||||
```
|
||||
|
||||
### 带详细描述的示例
|
||||
|
||||
```bash
|
||||
git commit -m "feat：添加存档系统
|
||||
|
||||
- 实现游戏进度保存功能
|
||||
- 支持多个存档槽位
|
||||
- 添加自动保存机制
|
||||
|
||||
关联 Issue #12"
|
||||
```
|
||||
|
||||
### 场景和资源示例
|
||||
|
||||
```bash
|
||||
# 场景相关
|
||||
git commit -m "scene：创建战斗场景并配置相机"
|
||||
|
||||
# 资源相关
|
||||
git commit -m "asset：导入角色动画资源包"
|
||||
|
||||
# UI 相关
|
||||
git commit -m "ui：完成主菜单界面设计"
|
||||
|
||||
# 音频相关
|
||||
git commit -m "audio：添加脚步声和跳跃音效"
|
||||
```
|
||||
|
||||
### 游戏开发示例
|
||||
|
||||
```bash
|
||||
# 游戏玩法
|
||||
git commit -m "gameplay：实现道具拾取和使用系统"
|
||||
|
||||
# 关卡设计
|
||||
git commit -m "level：设计并实现第三关卡"
|
||||
|
||||
# 配置调整
|
||||
git commit -m "config：平衡敌人血量和伤害数值"
|
||||
|
||||
# 插件集成
|
||||
git commit -m "plugin：添加粒子效果插件"
|
||||
```
|
||||
|
||||
### 重构和优化示例
|
||||
|
||||
```bash
|
||||
# 代码重构
|
||||
git commit -m "refactor：重构角色状态机逻辑"
|
||||
|
||||
# 性能优化
|
||||
git commit -m "perf：优化大量敌人时的渲染性能"
|
||||
|
||||
# 代码格式
|
||||
git commit -m "style：统一 GDScript 代码风格"
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **使用中文冒号**：类型后使用中文冒号 `：` 而非英文冒号 `:`
|
||||
2. **简短明确**：描述应简洁明了，一般不超过 50 个字符
|
||||
3. **动词开头**：描述部分使用动词开头，如"添加"、"修复"、"更新"等
|
||||
4. **一次提交一个改动**：每次提交应该只包含一个逻辑改动
|
||||
5. **详细描述**：对于复杂的改动，应该添加详细描述说明改动的原因和影响
|
||||
|
||||
## 分支命名规范
|
||||
|
||||
```bash
|
||||
# 功能分支
|
||||
feature/角色系统
|
||||
feature/存档功能
|
||||
|
||||
# 修复分支
|
||||
fix/碰撞检测
|
||||
fix/音频播放
|
||||
|
||||
# 开发分支
|
||||
dev
|
||||
develop
|
||||
|
||||
# 发布分支
|
||||
release/v1.0.0
|
||||
release/v1.1.0
|
||||
```
|
||||
|
||||
## 工具推荐
|
||||
|
||||
- **Commitizen**: 交互式提交信息生成工具
|
||||
- **Git Hooks**: 使用 pre-commit 钩子自动检查提交格式
|
||||
- **Conventional Commits**: 遵循约定式提交规范
|
||||
592
docs/naming_convention.md
Normal file
592
docs/naming_convention.md
Normal file
@@ -0,0 +1,592 @@
|
||||
# Godot 项目命名规范
|
||||
|
||||
本文档定义了 whaleTown 项目的命名规范，以保持代码的一致性和可读性。
|
||||
|
||||
## 目录
|
||||
|
||||
- [场景文件](#场景文件)
|
||||
- [脚本文件](#脚本文件)
|
||||
- [节点命名](#节点命名)
|
||||
- [变量命名](#变量命名)
|
||||
- [函数命名](#函数命名)
|
||||
- [常量命名](#常量命名)
|
||||
- [资源文件](#资源文件)
|
||||
- [目录结构](#目录结构)
|
||||
|
||||
---
|
||||
|
||||
## 场景文件
|
||||
|
||||
**规则**：下划线分隔 + `_scene` 或 `_prefab` 后缀
|
||||
|
||||
### 场景类型
|
||||
|
||||
- **主场景**：`_scene` 后缀，表示完整的游戏场景
|
||||
- **预制体**：`_prefab` 后缀，表示可复用的场景组件
|
||||
|
||||
### 示例
|
||||
|
||||
```
|
||||
✅ 正确
|
||||
main_scene.tscn # 主场景
|
||||
battle_scene.tscn # 战斗场景
|
||||
menu_scene.tscn # 菜单场景
|
||||
player_prefab.tscn # 玩家预制体
|
||||
enemy_boss_prefab.tscn # Boss 敌人预制体
|
||||
ui_dialog_prefab.tscn # 对话框预制体
|
||||
|
||||
❌ 错误
|
||||
MainScene.tscn # 不使用大驼峰
|
||||
main.tscn # 缺少 _scene 后缀
|
||||
player.tscn # 预制体缺少 _prefab 后缀
|
||||
```
|
||||
|
||||
### 命名建议
|
||||
|
||||
- 场景名称应清晰表达场景用途
|
||||
- 多个单词使用下划线分隔
|
||||
- 避免使用缩写，除非是通用缩写（如 ui、hp）
|
||||
|
||||
---
|
||||
|
||||
## 脚本文件
|
||||
|
||||
**规则**：大驼峰命名（PascalCase），`.gd` 扩展名
|
||||
|
||||
### 脚本类型
|
||||
|
||||
- **控制器脚本**：`Controller` 后缀
|
||||
- **管理器脚本**：`Manager` 后缀
|
||||
- **UI 脚本**：`UI_` 前缀
|
||||
- **数据类**：`Data` 后缀
|
||||
- **工具类**：`Utils` 或 `Helper` 后缀
|
||||
|
||||
### 示例
|
||||
|
||||
```
|
||||
✅ 正确
|
||||
PlayerController.gd # 玩家控制器
|
||||
EnemyAI.gd # 敌人 AI
|
||||
GameManager.gd # 游戏管理器
|
||||
AudioManager.gd # 音频管理器
|
||||
UI_MainMenu.gd # 主菜单 UI
|
||||
UI_HealthBar.gd # 血条 UI
|
||||
PlayerData.gd # 玩家数据类
|
||||
SaveData.gd # 存档数据类
|
||||
MathUtils.gd # 数学工具类
|
||||
StringHelper.gd # 字符串辅助类
|
||||
|
||||
❌ 错误
|
||||
player_controller.gd # 不使用下划线
|
||||
playerController.gd # 不使用小驼峰
|
||||
player.gd # 缺少明确的类型后缀
|
||||
PLAYER.gd # 不使用全大写
|
||||
```
|
||||
|
||||
### 命名建议
|
||||
|
||||
- 脚本名称应与类名一致
|
||||
- 一个脚本文件只包含一个主要类
|
||||
- 使用清晰的后缀表明脚本用途
|
||||
|
||||
---
|
||||
|
||||
## 节点命名
|
||||
|
||||
**规则**：小驼峰命名（camelCase）
|
||||
|
||||
### 节点类型
|
||||
|
||||
- **UI 节点**：描述性名称，如 `startButton`、`healthBar`
|
||||
- **游戏对象**：对象名称，如 `player`、`enemy`
|
||||
- **容器节点**：用途 + Container，如 `itemContainer`
|
||||
- **特效节点**：效果 + Effect，如 `explosionEffect`
|
||||
|
||||
### 示例
|
||||
|
||||
```
|
||||
✅ 正确
|
||||
player # 玩家节点
|
||||
enemy # 敌人节点
|
||||
mainCamera # 主相机
|
||||
playerHpBar # 玩家血条
|
||||
startButton # 开始按钮
|
||||
pauseMenu # 暂停菜单
|
||||
itemContainer # 物品容器
|
||||
backgroundMusic # 背景音乐
|
||||
explosionEffect # 爆炸特效
|
||||
collisionShape # 碰撞形状
|
||||
|
||||
❌ 错误
|
||||
Player # 不使用大驼峰
|
||||
player_hp_bar # 不使用下划线
|
||||
StartButton # 不使用大驼峰
|
||||
PLAYER # 不使用全大写
|
||||
btn_start # 避免缩写
|
||||
```
|
||||
|
||||
### 命名建议
|
||||
|
||||
- 节点名称应简洁明了
|
||||
- 同类型节点可以添加数字后缀，如 `enemy1`、`enemy2`
|
||||
- 避免使用无意义的名称，如 `Node2D`、`Control`
|
||||
|
||||
---
|
||||
|
||||
## 变量命名
|
||||
|
||||
**规则**：小驼峰命名（camelCase），可选类型前缀
|
||||
|
||||
### 变量类型前缀（可选）
|
||||
|
||||
使用类型前缀可以提升代码可读性，但不是强制要求。
|
||||
|
||||
| 类型 | 前缀 | 示例 |
|
||||
|------|------|------|
|
||||
| 整数 | `i` | `iHealth`, `iScore` |
|
||||
| 浮点数 | `f` | `fSpeed`, `fDamage` |
|
||||
| 字符串 | `s` | `sPlayerName`, `sDialogText` |
|
||||
| 布尔值 | `b` 或 `is/has` | `bIsAlive`, `isJumping`, `hasKey` |
|
||||
| 数组 | `a` 或复数 | `aEnemies`, `enemies` |
|
||||
| 字典 | `d` | `dPlayerStats` |
|
||||
| 节点引用 | 无前缀 | `playerNode`, `healthBar` |
|
||||
|
||||
### 示例
|
||||
|
||||
```gdscript
|
||||
✅ 正确（带前缀）
|
||||
var iHealth: int = 100
|
||||
var fSpeed: float = 5.0
|
||||
var sPlayerName: String = "Player"
|
||||
var bIsAlive: bool = true
|
||||
var aEnemies: Array = []
|
||||
var dInventory: Dictionary = {}
|
||||
|
||||
✅ 正确（不带前缀）
|
||||
var health: int = 100
|
||||
var speed: float = 5.0
|
||||
var playerName: String = "Player"
|
||||
var isAlive: bool = true
|
||||
var enemies: Array = []
|
||||
var inventory: Dictionary = {}
|
||||
|
||||
✅ 正确（布尔值使用 is/has）
|
||||
var isJumping: bool = false
|
||||
var hasWeapon: bool = true
|
||||
var canMove: bool = true
|
||||
|
||||
❌ 错误
|
||||
var Health: int = 100 # 不使用大驼峰
|
||||
var player_name: String = "" # 不使用下划线
|
||||
var SPEED: float = 5.0 # 常量才使用全大写
|
||||
var i: int = 0 # 循环变量除外，其他避免单字母
|
||||
```
|
||||
|
||||
### 成员变量
|
||||
|
||||
```gdscript
|
||||
# 导出变量（Inspector 可见）
|
||||
@export var maxHealth: int = 100
|
||||
@export var moveSpeed: float = 200.0
|
||||
@export var playerName: String = "Player"
|
||||
|
||||
# 私有变量（以下划线开头）
|
||||
var _currentHealth: int
|
||||
var _isInitialized: bool = false
|
||||
|
||||
# 节点引用
|
||||
@onready var healthBar: ProgressBar = $HealthBar
|
||||
@onready var animationPlayer: AnimationPlayer = $AnimationPlayer
|
||||
```
|
||||
|
||||
### 命名建议
|
||||
|
||||
- 变量名应具有描述性
|
||||
- 布尔变量使用 `is`、`has`、`can` 等前缀
|
||||
- 私有变量以下划线 `_` 开头
|
||||
- 避免使用单字母变量名（循环变量 `i`、`j` 除外）
|
||||
|
||||
---
|
||||
|
||||
## 函数命名
|
||||
|
||||
**规则**：小驼峰命名（camelCase），动词开头
|
||||
|
||||
### 函数类型
|
||||
|
||||
- **获取函数**：`get` 前缀
|
||||
- **设置函数**：`set` 前缀
|
||||
- **判断函数**：`is`、`has`、`can` 前缀，返回布尔值
|
||||
- **事件处理**：`on` 或 `_on` 前缀
|
||||
- **初始化函数**：`init` 或 `initialize`
|
||||
- **更新函数**：`update` 前缀
|
||||
- **私有函数**：`_` 前缀
|
||||
|
||||
### 示例
|
||||
|
||||
```gdscript
|
||||
✅ 正确
|
||||
func getPlayerPosition() -> Vector2:
|
||||
return position
|
||||
|
||||
func setHealth(value: int) -> void:
|
||||
health = value
|
||||
|
||||
func isAlive() -> bool:
|
||||
return health > 0
|
||||
|
||||
func hasItem(itemName: String) -> bool:
|
||||
return inventory.has(itemName)
|
||||
|
||||
func canJump() -> bool:
|
||||
return isOnFloor and not isJumping
|
||||
|
||||
func onButtonPressed() -> void:
|
||||
print("Button pressed")
|
||||
|
||||
func _onTimerTimeout() -> void:
|
||||
# 信号处理函数
|
||||
pass
|
||||
|
||||
func initializePlayer() -> void:
|
||||
health = maxHealth
|
||||
position = startPosition
|
||||
|
||||
func updateMovement(delta: float) -> void:
|
||||
position += velocity * delta
|
||||
|
||||
func _calculateDamage(baseDamage: int) -> int:
|
||||
# 私有函数
|
||||
return baseDamage * damageMultiplier
|
||||
|
||||
❌ 错误
|
||||
func GetPlayerPosition(): # 不使用大驼峰
|
||||
func get_player_position(): # 不使用下划线
|
||||
func PlayerPosition(): # 缺少动词
|
||||
func JUMP(): # 不使用全大写
|
||||
```
|
||||
|
||||
### 内置函数重写
|
||||
|
||||
```gdscript
|
||||
# Godot 内置函数使用下划线命名（保持原样）
|
||||
func _ready() -> void:
|
||||
pass
|
||||
|
||||
func _process(delta: float) -> void:
|
||||
pass
|
||||
|
||||
func _physics_process(delta: float) -> void:
|
||||
pass
|
||||
|
||||
func _input(event: InputEvent) -> void:
|
||||
pass
|
||||
```
|
||||
|
||||
### 命名建议
|
||||
|
||||
- 函数名应清晰表达功能
|
||||
- 使用动词开头，如 `get`、`set`、`update`、`calculate`
|
||||
- 参数名称也使用小驼峰命名
|
||||
- 私有函数以下划线开头
|
||||
|
||||
---
|
||||
|
||||
## 常量命名
|
||||
|
||||
**规则**：全大写 + 下划线分隔
|
||||
|
||||
### 示例
|
||||
|
||||
```gdscript
|
||||
✅ 正确
|
||||
const MAX_HEALTH: int = 100
|
||||
const DEFAULT_SPEED: float = 200.0
|
||||
const PLAYER_NAME: String = "Player"
|
||||
const GRAVITY: float = 980.0
|
||||
const JUMP_FORCE: float = -400.0
|
||||
const MAX_ENEMIES: int = 10
|
||||
const SAVE_FILE_PATH: String = "user://save.dat"
|
||||
const SCREEN_WIDTH: int = 1920
|
||||
const SCREEN_HEIGHT: int = 1080
|
||||
|
||||
❌ 错误
|
||||
const maxHealth: int = 100 # 不使用小驼峰
|
||||
const MaxHealth: int = 100 # 不使用大驼峰
|
||||
const max_health: int = 100 # 不使用小写
|
||||
```
|
||||
|
||||
### 枚举命名
|
||||
|
||||
```gdscript
|
||||
# 枚举名使用大驼峰
|
||||
enum PlayerState {
|
||||
IDLE, # 枚举值使用全大写
|
||||
WALKING,
|
||||
RUNNING,
|
||||
JUMPING,
|
||||
ATTACKING
|
||||
}
|
||||
|
||||
enum EnemyType {
|
||||
NORMAL,
|
||||
ELITE,
|
||||
BOSS
|
||||
}
|
||||
|
||||
# 使用
|
||||
var currentState: PlayerState = PlayerState.IDLE
|
||||
```
|
||||
|
||||
### 命名建议
|
||||
|
||||
- 常量名应清晰表达含义
|
||||
- 使用全大写和下划线
|
||||
- 枚举类型名使用大驼峰，枚举值使用全大写
|
||||
|
||||
---
|
||||
|
||||
## 资源文件
|
||||
|
||||
**规则**：下划线分隔，小写字母
|
||||
|
||||
### 图片资源
|
||||
|
||||
```
|
||||
✅ 正确
|
||||
bg_main_menu.png # 背景图
|
||||
sprite_player_idle.png # 精灵图
|
||||
icon_sword.png # 图标
|
||||
ui_button_normal.png # UI 元素
|
||||
tile_grass_01.png # 瓦片图
|
||||
|
||||
❌ 错误
|
||||
BgMainMenu.png # 不使用大驼峰
|
||||
bg-main-menu.png # 不使用连字符
|
||||
BACKGROUND.png # 不使用全大写
|
||||
```
|
||||
|
||||
### 音频资源
|
||||
|
||||
```
|
||||
✅ 正确
|
||||
sound_jump.wav # 音效
|
||||
sound_explosion.wav
|
||||
music_battle.ogg # 音乐
|
||||
music_menu.ogg
|
||||
voice_npc_greeting.wav # 语音
|
||||
|
||||
❌ 错误
|
||||
Jump.wav
|
||||
sound-jump.wav
|
||||
SOUND_JUMP.wav
|
||||
```
|
||||
|
||||
### 其他资源
|
||||
|
||||
```
|
||||
✅ 正确
|
||||
font_main.ttf # 字体
|
||||
shader_water.gdshader # 着色器
|
||||
material_metal.tres # 材质
|
||||
animation_walk.res # 动画
|
||||
|
||||
❌ 错误
|
||||
MainFont.ttf
|
||||
font-main.ttf
|
||||
FONT_MAIN.ttf
|
||||
```
|
||||
|
||||
### 资源命名建议
|
||||
|
||||
- 使用类型前缀，如 `bg_`、`sprite_`、`sound_`、`music_`
|
||||
- 多个单词使用下划线分隔
|
||||
- 全部使用小写字母
|
||||
- 同系列资源使用数字后缀，如 `tile_01.png`、`tile_02.png`
|
||||
|
||||
---
|
||||
|
||||
## 目录结构
|
||||
|
||||
### 目录命名
|
||||
|
||||
**规则**：小写字母 + 下划线分隔
|
||||
|
||||
```
|
||||
✅ 正确
|
||||
scenes/ # 场景目录
|
||||
scripts/ # 脚本目录
|
||||
assets/ # 资源目录
|
||||
sprites/ # 精灵图
|
||||
sounds/ # 音效
|
||||
music/ # 音乐
|
||||
fonts/ # 字体
|
||||
data/ # 数据目录
|
||||
levels/ # 关卡数据
|
||||
configs/ # 配置文件
|
||||
addons/ # 插件目录
|
||||
tests/ # 测试目录
|
||||
|
||||
❌ 错误
|
||||
Scenes/ # 不使用大写
|
||||
Scripts/
|
||||
Assets/
|
||||
```
|
||||
|
||||
### 推荐的项目结构
|
||||
|
||||
```
|
||||
whaleTown/
|
||||
├── scenes/
|
||||
│ ├── main_scene.tscn
|
||||
│ ├── battle_scene.tscn
|
||||
│ └── prefabs/
|
||||
│ ├── player_prefab.tscn
|
||||
│ └── enemy_prefab.tscn
|
||||
├── scripts/
|
||||
│ ├── PlayerController.gd
|
||||
│ ├── EnemyAI.gd
|
||||
│ ├── GameManager.gd
|
||||
│ └── ui/
|
||||
│ ├── UI_MainMenu.gd
|
||||
│ └── UI_HealthBar.gd
|
||||
├── assets/
|
||||
│ ├── sprites/
|
||||
│ │ ├── sprite_player_idle.png
|
||||
│ │ └── sprite_enemy_walk.png
|
||||
│ ├── sounds/
|
||||
│ │ ├── sound_jump.wav
|
||||
│ │ └── sound_attack.wav
|
||||
│ ├── music/
|
||||
│ │ └── music_battle.ogg
|
||||
│ └── fonts/
|
||||
│ └── font_main.ttf
|
||||
├── data/
|
||||
│ ├── levels/
|
||||
│ │ └── level_01.json
|
||||
│ └── configs/
|
||||
│ └── game_config.json
|
||||
└── addons/
|
||||
└── plugin_name/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 完整示例
|
||||
|
||||
### 场景文件：`player_prefab.tscn`
|
||||
|
||||
```
|
||||
[节点树]
|
||||
player # 根节点（小驼峰）
|
||||
├── sprite # 精灵节点
|
||||
├── collisionShape # 碰撞形状
|
||||
├── animationPlayer # 动画播放器
|
||||
└── healthBar # 血条
|
||||
```
|
||||
|
||||
### 脚本文件：`PlayerController.gd`
|
||||
|
||||
```gdscript
|
||||
extends CharacterBody2D
|
||||
|
||||
# 常量（全大写 + 下划线）
|
||||
const MAX_HEALTH: int = 100
|
||||
const DEFAULT_SPEED: float = 200.0
|
||||
const JUMP_FORCE: float = -400.0
|
||||
|
||||
# 导出变量（小驼峰）
|
||||
@export var moveSpeed: float = DEFAULT_SPEED
|
||||
@export var maxHealth: int = MAX_HEALTH
|
||||
|
||||
# 成员变量（小驼峰，可选类型前缀）
|
||||
var currentHealth: int
|
||||
var isJumping: bool = false
|
||||
var hasDoubleJump: bool = false
|
||||
|
||||
# 私有变量（下划线前缀）
|
||||
var _velocity: Vector2 = Vector2.ZERO
|
||||
var _isInitialized: bool = false
|
||||
|
||||
# 节点引用
|
||||
@onready var sprite: Sprite2D = $sprite
|
||||
@onready var animationPlayer: AnimationPlayer = $animationPlayer
|
||||
@onready var healthBar: ProgressBar = $healthBar
|
||||
|
||||
# 内置函数
|
||||
func _ready() -> void:
|
||||
initializePlayer()
|
||||
|
||||
func _physics_process(delta: float) -> void:
|
||||
updateMovement(delta)
|
||||
updateAnimation()
|
||||
|
||||
# 公共函数（小驼峰，动词开头）
|
||||
func initializePlayer() -> void:
|
||||
currentHealth = maxHealth
|
||||
updateHealthBar()
|
||||
_isInitialized = true
|
||||
|
||||
func takeDamage(damage: int) -> void:
|
||||
currentHealth -= damage
|
||||
if currentHealth <= 0:
|
||||
die()
|
||||
updateHealthBar()
|
||||
|
||||
func heal(amount: int) -> void:
|
||||
currentHealth = min(currentHealth + amount, maxHealth)
|
||||
updateHealthBar()
|
||||
|
||||
func isAlive() -> bool:
|
||||
return currentHealth > 0
|
||||
|
||||
func canJump() -> bool:
|
||||
return is_on_floor() or hasDoubleJump
|
||||
|
||||
# 私有函数（下划线前缀）
|
||||
func _calculateDamage(baseDamage: int) -> int:
|
||||
return baseDamage * 2
|
||||
|
||||
func updateMovement(delta: float) -> void:
|
||||
# 移动逻辑
|
||||
pass
|
||||
|
||||
func updateAnimation() -> void:
|
||||
# 动画逻辑
|
||||
pass
|
||||
|
||||
func updateHealthBar() -> void:
|
||||
if healthBar:
|
||||
healthBar.value = float(currentHealth) / float(maxHealth) * 100.0
|
||||
|
||||
func die() -> void:
|
||||
print("Player died")
|
||||
queue_free()
|
||||
|
||||
# 信号处理（_on 前缀）
|
||||
func _onAreaEntered(area: Area2D) -> void:
|
||||
print("Area entered: ", area.name)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
遵循统一的命名规范可以：
|
||||
|
||||
- ✅ 提高代码可读性
|
||||
- ✅ 便于团队协作
|
||||
- ✅ 减少命名冲突
|
||||
- ✅ 方便代码维护
|
||||
- ✅ 提升开发效率
|
||||
|
||||
记住核心原则：
|
||||
|
||||
1. **场景文件**：`下划线_scene/prefab`
|
||||
2. **脚本文件**：`PascalCase.gd`
|
||||
3. **节点名称**：`camelCase`
|
||||
4. **变量/函数**：`camelCase`
|
||||
5. **常量**：`UPPER_CASE`
|
||||
6. **资源文件**：`lower_case`
|
||||
|
||||
保持一致，代码更清晰！
|
||||
Reference in New Issue
Block a user