forked from datawhale/whale-town-front
docs: 文档中文化和清理
新增: - 开发规范.md (翻译自CLAUDE.md) 重命名为中文: - project_structure.md 项目结构说明.md - naming_convention.md 命名规范.md - code_comment_guide.md 代码注释规范.md - git_commit_guide.md Git提交规范.md - api-documentation.md API接口文档.md - network_manager_setup.md 网络管理器设置.md - setup.md 项目设置指南.md - testing_guide.md 测试指南.md - web_deployment_guide.md Web部署指南.md - module_development.md 模块开发指南.md - performance_optimization.md 性能优化指南.md - scene_design.md 场景设计规范.md - auth/form_validation.md auth/表单验证规范.md - auth/testing_guide.md auth/认证测试指南.md 删除总结性文档: - final_update_summary.md - web_deployment_changelog.md - CLAUDE.md
This commit is contained in:
96
CLAUDE.md
96
CLAUDE.md
@@ -1,96 +0,0 @@
|
|||||||
# 🎯 CLAUDE.md - WhaleTown Project Instructions
|
|
||||||
|
|
||||||
## 1. Project Vision & Context
|
|
||||||
- **Project**: "WhaleTown" - A 2D top-down pixel art RPG.
|
|
||||||
- **Engine**: Godot 4.2+ (Strictly NO Godot 3.x syntax).
|
|
||||||
- **Architecture**: Strictly layered: `_Core` (Framework), `Scenes` (Gameplay), `UI` (Interface).
|
|
||||||
- **Core Principle**: "Signal Up, Call Down". High decoupling via `EventSystem`.
|
|
||||||
|
|
||||||
## 2. 🛠 Command Reference & Setup
|
|
||||||
- **Input Map (Required Configuration)**:
|
|
||||||
- `move_left`, `move_right`, `move_up`, `move_down` (WASD / Arrows)
|
|
||||||
- `interact` (E Key / Space)
|
|
||||||
- `pause` (ESC)
|
|
||||||
- **Run Game**: `godot --path .`
|
|
||||||
- **Run Tests (GUT)**: `godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/ -ginclude_subdirs`
|
|
||||||
- **Init Structure**: `mkdir -p _Core/managers _Core/systems Scenes/Maps Scenes/Entities Scenes/Components UI/Windows UI/HUD Assets/Sprites tests/unit tests/integration`
|
|
||||||
|
|
||||||
## 3. 📂 File Path Rules (STRICT LOWERCASE)
|
|
||||||
*Claude: Root folders MUST be lowercase. Scripts and Scenes MUST stay together.*
|
|
||||||
- **Core Managers**: `_Core/managers/[Name].gd`
|
|
||||||
- **Core Systems**: `_Core/systems/[Name].gd`
|
|
||||||
- **Entities**: `Scenes/Entities/[EntityName]/[EntityName].tscn` (Script `.gd` in same folder).
|
|
||||||
- **Maps**: `Scenes/Maps/[map_name].tscn`
|
|
||||||
- **Components**: `Scenes/Components/[ComponentName].gd` (Reusable logic nodes).
|
|
||||||
- **UI Windows**: `UI/Windows/[WindowName].tscn`
|
|
||||||
- **Tests**: `tests/[unit|integration]/test_[name].gd` (Folder is lowercase `tests`).
|
|
||||||
|
|
||||||
## 4. 📋 Coding Standards (The Law)
|
|
||||||
- **Type Safety**: ALWAYS use strict static typing: `var speed: float = 100.0`, `func _ready() -> void`.
|
|
||||||
- **Naming Conventions**:
|
|
||||||
- `class_name PascalCase` at the top of every script.
|
|
||||||
- Variables/Functions: `snake_case`. Constants: `SCREAMING_SNAKE_CASE`.
|
|
||||||
- Private members: Prefix with underscore `_` (e.g., `var _health: int`).
|
|
||||||
- **Node Access**: Use `%UniqueName` for UI and internal scene components.
|
|
||||||
- **Signals**: Use "Signal Up, Call Down". Parent calls child methods; Child emits signals.
|
|
||||||
- **Forbidden Patterns**:
|
|
||||||
- ❌ NO `yield()` -> Use `await`.
|
|
||||||
- ❌ NO `get_node()` in `_process` -> Cache with `@onready`.
|
|
||||||
- ❌ NO Linear Filter -> All Sprite2D/TileMap resources MUST use **Nearest** filter.
|
|
||||||
|
|
||||||
## 5. 🏛 Architecture & Communication
|
|
||||||
- **EventSystem**: Use `_Core/systems/EventSystem.gd` for cross-module messaging.
|
|
||||||
- **Event Registry**: Use `class_name EventNames` in `_Core/EventNames.gd`.
|
|
||||||
```gdscript
|
|
||||||
class_name EventNames
|
|
||||||
const PLAYER_MOVED = "player_moved"
|
|
||||||
const INTERACT_PRESSED = "interact_pressed"
|
|
||||||
const NPC_TALKED = "npc_talked"
|
|
||||||
Singletons: Only GameManager, SceneManager, EventSystem allowed as Autoloads.
|
|
||||||
Decoupling: Low-level entities MUST NOT reference GameManager. Use events.
|
|
||||||
6. 🏗 Implementation Details
|
|
||||||
Player: CharacterBody2D. Must include Camera2D with position_smoothing_enabled = true.
|
|
||||||
NPC/Interactables: Use Area2D named InteractionArea. Trigger via EventSystem.
|
|
||||||
TileMap Layers:
|
|
||||||
Layer 0: Ground (No collision).
|
|
||||||
Layer 1: Obstacles (Physics Layer enabled).
|
|
||||||
Layer 2: Decoration (Y-Sort enabled).
|
|
||||||
Camera: Must auto-calculate limits via TileMap.get_used_rect().
|
|
||||||
7. 🧪 Testing Requirements (MANDATORY)
|
|
||||||
Coverage: Every Manager/System in _Core/ MUST have a GUT test.
|
|
||||||
Naming: Test files must start with test_ and extend GutTest.
|
|
||||||
Example:
|
|
||||||
code
|
|
||||||
Gdscript
|
|
||||||
extends GutTest
|
|
||||||
func test_event_emission():
|
|
||||||
var sender = Node.new()
|
|
||||||
watch_signals(EventSystem)
|
|
||||||
EventSystem.emit_event(EventNames.PLAYER_MOVED, {})
|
|
||||||
assert_signal_emitted(EventSystem, "event_raised")
|
|
||||||
8. 🧘 The Zen of Development
|
|
||||||
Juice or Death: Every interaction (UI popup, NPC talk) MUST have a Tween placeholder.
|
|
||||||
Zero Magic Numbers: All speeds/timers MUST be @export or defined in Config/.
|
|
||||||
Simplicity: If a function does two things, split it.
|
|
||||||
Back of the Fence: Hidden logic (like ResponseHandler.gd) must be as clean as the HUD.
|
|
||||||
9. 📝 Code Template (Entity Pattern)
|
|
||||||
code
|
|
||||||
Gdscript
|
|
||||||
extends CharacterBody2D
|
|
||||||
class_name Player
|
|
||||||
|
|
||||||
# 1. Exports & Constants
|
|
||||||
@export var move_speed: float = 200.0
|
|
||||||
|
|
||||||
# 2. Node References
|
|
||||||
@onready var sprite: Sprite2D = %Sprite2D
|
|
||||||
|
|
||||||
# 3. Lifecycle
|
|
||||||
func _physics_process(delta: float) -> void:
|
|
||||||
_move(delta)
|
|
||||||
|
|
||||||
# 4. Private Methods
|
|
||||||
func _move(_delta: float) -> void:
|
|
||||||
var dir := Input.get_vector("move_left", "move_right", "move_up", "move_down")
|
|
||||||
velocity = dir * move_speed
|
|
||||||
move_and_slide()
|
|
||||||
344
README.md
344
README.md
@@ -23,19 +23,13 @@ Whale Town 是一个功能完整的像素游戏前端客户端，采用模块化
|
|||||||
|
|
||||||
## 🚀 快速开始
|
## 🚀 快速开始
|
||||||
|
|
||||||
<<<<<<< HEAD
|
|
||||||
### 📋 环境要求
|
### 📋 环境要求
|
||||||
|
|
||||||
- **Godot Engine** >= 4.5.0 (推荐 4.5.1)
|
- **Godot Engine** >= 4.5.0 (推荐 4.5.1)(https://godotengine.org/download)
|
||||||
- **Python** >= 3.7.0 (用于API测试，可选)
|
- **Python** >= 3.7.0 (用于API测试，可选)
|
||||||
- **Git** >= 2.0.0
|
- **Git** >= 2.0.0
|
||||||
|
|
||||||
### 🛠️ 安装与运行
|
### 🛠️ 安装与运行
|
||||||
=======
|
|
||||||
### 环境要求
|
|
||||||
- [Godot Engine 4.5+](https://godotengine.org/download)
|
|
||||||
- Python 3.7+ (用于API测试和Web服务器)
|
|
||||||
>>>>>>> whale-town-front/main
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1. 克隆项目
|
# 1. 克隆项目
|
||||||
@@ -49,333 +43,12 @@ cd whale-town
|
|||||||
# 按F5或点击"运行"按钮启动游戏
|
# 按F5或点击"运行"按钮启动游戏
|
||||||
```
|
```
|
||||||
|
|
||||||
<<<<<<< HEAD
|
|
||||||
🎉 **游戏启动成功！** 进入认证界面开始体验
|
🎉 **游戏启动成功！** 进入认证界面开始体验
|
||||||
|
|
||||||
### 🧪 快速测试
|
### 🧪 快速测试
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# API接口测试
|
# API接口测试
|
||||||
=======
|
|
||||||
### Web版本部署
|
|
||||||
```bash
|
|
||||||
# Windows用户
|
|
||||||
tools\build_web.bat # 导出Web版本
|
|
||||||
tools\serve_web.bat # 启动本地测试服务器
|
|
||||||
|
|
||||||
# Linux/macOS用户
|
|
||||||
./tools/build_web.sh # 导出Web版本
|
|
||||||
./tools/serve_web.sh # 启动本地测试服务器
|
|
||||||
```
|
|
||||||
|
|
||||||
详细部署指南请查看: [Web部署完整指南](docs/web_deployment_guide.md)
|
|
||||||
|
|
||||||
## 🏗️ 项目架构
|
|
||||||
|
|
||||||
### 核心设计理念
|
|
||||||
项目采用 **分层架构** 和 **组件化设计**，遵循 Godot 最佳实践：
|
|
||||||
- **清晰的分层** - 框架层、玩法层、界面层明确分离
|
|
||||||
- **场景内聚** - 脚本紧邻场景文件，符合 Godot 原生开发习惯
|
|
||||||
- **高度解耦** - 通过事件系统和管理器通信
|
|
||||||
- **组件复用** - 可复用组件统一管理
|
|
||||||
- **标准化** - 统一的命名规范和目录结构
|
|
||||||
- **测试驱动** - 完整的测试体系和文档
|
|
||||||
|
|
||||||
### 目录结构
|
|
||||||
```
|
|
||||||
whaleTown/
|
|
||||||
├── _Core/ # [框架层] 游戏的底层框架，单例，全局管理器
|
|
||||||
│ ├── managers/ # 游戏管理器
|
|
||||||
│ │ ├── GameManager.gd # 游戏状态管理
|
|
||||||
│ │ ├── SceneManager.gd # 场景管理
|
|
||||||
│ │ ├── NetworkManager.gd # 网络通信
|
|
||||||
│ │ └── ResponseHandler.gd # API响应处理
|
|
||||||
│ ├── systems/ # 核心系统
|
|
||||||
│ │ └── EventSystem.gd # 事件系统
|
|
||||||
│ └── singletons/ # 其他单例（待扩展）
|
|
||||||
│
|
|
||||||
├── Scenes/ # [玩法层] 具体的游戏场景、实体、地图
|
|
||||||
│ ├── Maps/ # 地图场景
|
|
||||||
│ │ └── main_scene.tscn # 主游戏场景
|
|
||||||
│ ├── Entities/ # 游戏实体
|
|
||||||
│ │ ├── Player/ # 玩家实体
|
|
||||||
│ │ ├── NPC/ # NPC实体
|
|
||||||
│ │ └── Interactables/ # 交互物
|
|
||||||
│ └── Components/ # 可复用组件
|
|
||||||
│
|
|
||||||
├── UI/ # [界面层] 所有UI相关的预制体和逻辑
|
|
||||||
│ ├── HUD/ # 抬头显示（常驻）
|
|
||||||
│ ├── Windows/ # 模态窗口
|
|
||||||
│ │ └── LoginWindow.tscn # 登录窗口
|
|
||||||
│ ├── Dialog/ # 对话系统
|
|
||||||
│ └── Theme/ # 全局样式
|
|
||||||
│ ├── MainTheme.tres # 主主题
|
|
||||||
│ └── Fonts/ # 字体文件
|
|
||||||
│
|
|
||||||
├── Assets/ # [资源层] 美术、音频、字体
|
|
||||||
│ ├── Sprites/ # 精灵图
|
|
||||||
│ │ ├── icon/ # 图标
|
|
||||||
│ │ ├── materials/ # 材质
|
|
||||||
│ │ ├── shaders/ # 着色器
|
|
||||||
│ │ └── sprites/ # 精灵图
|
|
||||||
│ ├── Audio/ # 音频
|
|
||||||
│ └── Fonts/ # 字体
|
|
||||||
│
|
|
||||||
├── Config/ # [配置层] 游戏配置文件
|
|
||||||
│ ├── game_config.json # 游戏配置
|
|
||||||
│ └── zh_CN.json # 中文本地化
|
|
||||||
│
|
|
||||||
├── Utils/ # [工具层] 通用辅助脚本
|
|
||||||
│ └── StringUtils.gd # 字符串工具
|
|
||||||
│
|
|
||||||
├── Tests/ # [测试层] 单元测试脚本
|
|
||||||
│ ├── api/ # API接口测试
|
|
||||||
│ ├── auth/ # 认证UI测试
|
|
||||||
│ ├── unit/ # 单元测试
|
|
||||||
│ ├── integration/ # 集成测试
|
|
||||||
│ └── performance/ # 性能测试
|
|
||||||
│
|
|
||||||
├── docs/ # 项目文档
|
|
||||||
│ ├── auth/ # 认证相关文档
|
|
||||||
│ ├── api-documentation.md # API接口文档
|
|
||||||
│ ├── web_deployment_guide.md # Web部署完整指南
|
|
||||||
│ ├── web_deployment_changelog.md # Web部署更新日志
|
|
||||||
│ ├── project_structure.md # 项目结构说明
|
|
||||||
│ ├── naming_convention.md # 命名规范
|
|
||||||
│ ├── code_comment_guide.md # 代码注释规范
|
|
||||||
│ └── git_commit_guide.md # Git提交规范
|
|
||||||
│
|
|
||||||
├── tools/ # 开发工具和脚本
|
|
||||||
│ ├── build_web.bat # Windows Web导出脚本
|
|
||||||
│ ├── build_web.sh # Linux/macOS Web导出脚本
|
|
||||||
│ ├── serve_web.bat # Windows 本地服务器
|
|
||||||
│ └── serve_web.sh # Linux/macOS 本地服务器
|
|
||||||
│
|
|
||||||
├── REFACTORING.md # 项目结构重构文档
|
|
||||||
└── MIGRATION_COMPLETE.md # 迁移完成标记
|
|
||||||
```
|
|
||||||
|
|
||||||
### 架构层次说明
|
|
||||||
|
|
||||||
#### 1. 框架层 (_Core/)
|
|
||||||
- **职责**: 游戏的底层框架，与具体游戏逻辑无关
|
|
||||||
- **内容**: 单例管理器、核心系统
|
|
||||||
- **特点**: 自动加载，全局可访问
|
|
||||||
- **命名**: 使用下划线前缀 `_Core` 表示这是核心框架代码
|
|
||||||
|
|
||||||
#### 2. 玩法层 (Scenes/)
|
|
||||||
- **职责**: 游戏世界，地图和实体
|
|
||||||
- **内容**: 游戏场景、角色、NPC、交互物
|
|
||||||
- **特点**: 场景内聚，脚本紧邻场景文件
|
|
||||||
- **组织**: 按游戏世界的实体类型分类
|
|
||||||
|
|
||||||
#### 3. 界面层 (UI/)
|
|
||||||
- **职责**: 所有界面，HUD和弹窗
|
|
||||||
- **内容**: 常驻界面、模态窗口、对话系统、主题样式
|
|
||||||
- **特点**: 独立于游戏场景，便于UI开发和维护
|
|
||||||
- **组织**: 按界面类型和用途分类
|
|
||||||
|
|
||||||
#### 4. 资源层 (Assets/)
|
|
||||||
- **职责**: 纯美术资源
|
|
||||||
- **内容**: 精灵图、音频、字体等
|
|
||||||
- **特点**: 与代码分离，便于美术组独立工作
|
|
||||||
- **组织**: 按资源类型分类
|
|
||||||
|
|
||||||
#### 5. 配置层 (Config/)
|
|
||||||
- **职责**: 静态数据，策划可编辑
|
|
||||||
- **内容**: 游戏配置、本地化文件
|
|
||||||
- **特点**: 数据驱动，便于调整游戏参数
|
|
||||||
- **格式**: JSON 文件
|
|
||||||
|
|
||||||
#### 6. 工具层 (Utils/)
|
|
||||||
- **职责**: 通用辅助脚本
|
|
||||||
- **内容**: 工具函数库
|
|
||||||
- **特点**: 可被任何层调用
|
|
||||||
- **原则**: 无依赖，纯函数
|
|
||||||
|
|
||||||
### 核心系统
|
|
||||||
项目包含以下自动加载的核心系统（位于 [_Core/](./_Core/)）：
|
|
||||||
|
|
||||||
- **GameManager** - 全局游戏状态管理
|
|
||||||
- **SceneManager** - 场景切换管理
|
|
||||||
- **EventSystem** - 事件通信系统
|
|
||||||
- **NetworkManager** - 网络通信管理
|
|
||||||
- **ResponseHandler** - API响应处理
|
|
||||||
|
|
||||||
使用示例：
|
|
||||||
```gdscript
|
|
||||||
# 状态管理
|
|
||||||
GameManager.change_state(GameManager.GameState.IN_GAME)
|
|
||||||
|
|
||||||
# 场景切换（已更新路径）
|
|
||||||
SceneManager.change_scene("main") # → res://Scenes/Maps/main_scene.tscn
|
|
||||||
|
|
||||||
# 事件通信
|
|
||||||
EventSystem.emit_event("player_health_changed", 80)
|
|
||||||
EventSystem.connect_event("player_died", _on_player_died)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 设计原则
|
|
||||||
|
|
||||||
#### 1. 清晰的分层
|
|
||||||
- **_Core**: 框架代码，与具体游戏逻辑无关
|
|
||||||
- **Scenes**: 游戏世界，地图和实体
|
|
||||||
- **UI**: 所有界面，HUD和弹窗
|
|
||||||
- **Config**: 静态数据，策划可编辑
|
|
||||||
|
|
||||||
#### 2. 组件化设计
|
|
||||||
可复用组件放在 `Scenes/Components/` 下，使用组合优于继承的设计模式：
|
|
||||||
- InteractableArea.tscn - 让任何物体"可交互"
|
|
||||||
- MovementSync.gd - 网络位置同步
|
|
||||||
- NameTag3D.tscn - 头顶名字条
|
|
||||||
|
|
||||||
#### 3. 场景内聚
|
|
||||||
- 每个 .tscn 配套一个 .gd
|
|
||||||
- 脚本紧邻场景文件存放
|
|
||||||
- 符合 Godot 原生开发习惯
|
|
||||||
|
|
||||||
#### 4. 职责单一
|
|
||||||
```
|
|
||||||
UI/Windows/ - 模态窗口（登录、设置、商店）
|
|
||||||
UI/HUD/ - 常驻界面（聊天框、状态栏）
|
|
||||||
UI/Dialog/ - 对话系统
|
|
||||||
```
|
|
||||||
|
|
||||||
### 团队协作
|
|
||||||
- **美术组**: 主要在 [Assets/](./Assets/) 工作
|
|
||||||
- **策划组**: 主要在 [Config/](./Config/) 工作
|
|
||||||
- **程序组**: 主要在 [_Core/](./_Core/), [Scenes/](./Scenes/), [UI/](./UI/) 工作
|
|
||||||
- **测试组**: 主要在 [Tests/](./Tests/) 工作
|
|
||||||
|
|
||||||
## ✨ 主要功能
|
|
||||||
|
|
||||||
### 🔐 用户认证系统
|
|
||||||
- **用户注册** - 支持邮箱验证码验证
|
|
||||||
- **用户登录** - 多种登录方式（用户名/邮箱/手机号）
|
|
||||||
- **密码管理** - 密码重置和修改功能
|
|
||||||
- **GitHub OAuth** - 第三方登录集成
|
|
||||||
- **错误处理** - 完整的错误提示和频率限制
|
|
||||||
- **UI界面**: [UI/Windows/LoginWindow.tscn](UI/Windows/LoginWindow.tscn)
|
|
||||||
|
|
||||||
### 🌐 Web版本部署
|
|
||||||
- **自动化导出** - 一键导出Web版本
|
|
||||||
- **本地测试服务器** - 内置HTTP服务器用于测试
|
|
||||||
- **生产环境配置** - 完整的服务器配置指南
|
|
||||||
- **跨平台支持** - Windows、Linux、macOS全平台支持
|
|
||||||
- **性能优化** - 资源压缩和加载优化
|
|
||||||
|
|
||||||
### 🎮 游戏功能
|
|
||||||
- **主场景** - 游戏主界面和菜单系统 ([Scenes/Maps/main_scene.tscn](Scenes/Maps/main_scene.tscn))
|
|
||||||
- **认证场景** - 完整的登录注册界面
|
|
||||||
- **状态管理** - 用户状态和游戏状态管理
|
|
||||||
- **网络通信** - RESTful API集成 ([_Core/managers/NetworkManager.gd](_Core/managers/NetworkManager.gd))
|
|
||||||
|
|
||||||
### 🧪 测试体系
|
|
||||||
- **API测试** - 完整的接口测试脚本 ([Tests/api/](Tests/api/))
|
|
||||||
- **UI测试** - 认证界面的交互测试 ([Tests/auth/](Tests/auth/))
|
|
||||||
- **错误场景** - 边界条件和异常处理测试
|
|
||||||
|
|
||||||
## 🔧 开发规范
|
|
||||||
|
|
||||||
### 命名规范
|
|
||||||
- **场景文件**: `snake_case_scene.tscn` (如: `auth_scene.tscn`)
|
|
||||||
- **脚本文件**: `PascalCase.gd` (如: `AuthScene.gd`)
|
|
||||||
- **节点名称**: `camelCase` (如: `loginButton`)
|
|
||||||
- **变量/函数**: `camelCase` (如: `playerHealth`)
|
|
||||||
- **常量**: `UPPER_CASE` (如: `MAX_HEALTH`)
|
|
||||||
- **资源文件**: `snake_case` (如: `bg_auth_scene.png`)
|
|
||||||
|
|
||||||
### 代码注释规范
|
|
||||||
- **文件头注释**: 说明文件用途、主要功能和依赖关系
|
|
||||||
- **函数注释**: 包含参数说明、返回值和使用示例
|
|
||||||
- **复杂逻辑**: 添加行内注释解释业务逻辑和设计决策
|
|
||||||
- **特殊标记**: 使用 TODO、FIXME、NOTE 等标准标记
|
|
||||||
- **AI辅助**: 支持AI补充注释，提供详细的上下文信息
|
|
||||||
|
|
||||||
### Git 提交规范
|
|
||||||
使用格式：`<类型>：<描述>`
|
|
||||||
|
|
||||||
常用类型：`feat` `fix` `docs` `refactor` `scene` `asset` `ui` `test`
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git commit -m "feat：实现用户登录功能"
|
|
||||||
git commit -m "fix：修复429错误处理"
|
|
||||||
git commit -m "test：添加API接口测试"
|
|
||||||
git commit -m "docs：更新项目文档"
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📚 项目文档
|
|
||||||
|
|
||||||
### 核心文档
|
|
||||||
- 📋 [项目结构详解](docs/project_structure.md) - 完整的架构说明
|
|
||||||
- 📝 [命名规范](docs/naming_convention.md) - 详细的命名规则
|
|
||||||
- 💬 [代码注释规范](docs/code_comment_guide.md) - 注释标准和AI辅助指南
|
|
||||||
- 🔀 [Git提交规范](docs/git_commit_guide.md) - 提交信息标准
|
|
||||||
- 🌐 [Web部署指南](docs/web_deployment_guide.md) - 完整的Web部署文档
|
|
||||||
|
|
||||||
### API和测试文档
|
|
||||||
- 🔌 [API接口文档](docs/api-documentation.md) - 完整的API说明和测试指南
|
|
||||||
- 🔐 [认证系统文档](docs/auth/) - 用户认证相关文档
|
|
||||||
- 🧪 [API测试指南](tests/api/README.md) - API测试使用方法
|
|
||||||
- 🎮 [认证UI测试](tests/auth/README.md) - UI测试场景说明
|
|
||||||
|
|
||||||
## 🛠️ 开发指南
|
|
||||||
|
|
||||||
### 添加新场景
|
|
||||||
1. 在 [Scenes/](./Scenes/) 对应分类下创建场景文件
|
|
||||||
2. 脚本文件紧邻场景文件存放（场景内聚原则）
|
|
||||||
3. 在 [_Core/managers/SceneManager.gd](_Core/managers/SceneManager.gd) 中注册场景路径
|
|
||||||
4. 使用 `SceneManager.change_scene()` 切换场景
|
|
||||||
|
|
||||||
示例：
|
|
||||||
```gdscript
|
|
||||||
# 在 SceneManager.gd 中注册
|
|
||||||
var scene_paths: Dictionary = {
|
|
||||||
"battle": "res://Scenes/Maps/battle_scene.tscn",
|
|
||||||
"shop": "res://UI/Windows/ShopWindow.tscn",
|
|
||||||
}
|
|
||||||
|
|
||||||
# 使用
|
|
||||||
SceneManager.change_scene("battle")
|
|
||||||
```
|
|
||||||
|
|
||||||
### 创建可复用组件
|
|
||||||
1. 在 [Scenes/Components/](./Scenes/Components/) 创建组件场景
|
|
||||||
2. 实现标准接口，保持组件独立性
|
|
||||||
3. 通过 [EventSystem](_Core/systems/EventSystem.gd) 与其他模块通信
|
|
||||||
4. 组件可以被任何场景实例化复用
|
|
||||||
|
|
||||||
### 添加UI界面
|
|
||||||
1. **模态窗口** → 放入 [UI/Windows/](./UI/Windows/)
|
|
||||||
2. **常驻界面** → 放入 [UI/HUD/](./UI/HUD/)
|
|
||||||
3. **对话系统** → 放入 [UI/Dialog/](./UI/Dialog/)
|
|
||||||
4. UI脚本紧邻场景文件，保持内聚
|
|
||||||
|
|
||||||
### 资源管理
|
|
||||||
- **精灵图** → 放入 [Assets/Sprites/](./Assets/Sprites/) 对应分类
|
|
||||||
- **音频文件** → 放入 [Assets/Audio/](./Assets/Audio/) 对应分类
|
|
||||||
- **字体文件** → 放入 [UI/Theme/Fonts/](./UI/Theme/Fonts/)
|
|
||||||
- **配置文件** → 放入 [Config/](./Config/)
|
|
||||||
- 遵循命名规范，使用英文小写+下划线
|
|
||||||
|
|
||||||
### 路径映射参考
|
|
||||||
|
|
||||||
| 功能类型 | 旧路径 | 新路径 |
|
|
||||||
|---------|--------|--------|
|
|
||||||
| 核心管理器 | `core/managers/` | [_Core/managers/](_Core/managers/) |
|
|
||||||
| 游戏场景 | `scenes/main_scene.tscn` | [Scenes/Maps/main_scene.tscn](Scenes/Maps/main_scene.tscn) |
|
|
||||||
| 登录界面 | `scenes/auth_scene.tscn` | [UI/Windows/LoginWindow.tscn](UI/Windows/LoginWindow.tscn) |
|
|
||||||
| 配置文件 | `data/configs/` | [Config/](Config/) |
|
|
||||||
| 工具类 | `core/utils/` | [Utils/](Utils/) |
|
|
||||||
|
|
||||||
详细的重构说明请查看：[REFACTORING.md](REFACTORING.md)
|
|
||||||
|
|
||||||
### API接口测试
|
|
||||||
项目提供了完整的Python测试脚本来验证API接口：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 快速测试API连通性
|
|
||||||
>>>>>>> whale-town-front/main
|
|
||||||
python tests/api/simple_api_test.py
|
python tests/api/simple_api_test.py
|
||||||
|
|
||||||
# 完整功能测试
|
# 完整功能测试
|
||||||
@@ -392,7 +65,6 @@ python tests/api/api_test.py --verbose
|
|||||||
|
|
||||||
## 🎓 新开发者指南
|
## 🎓 新开发者指南
|
||||||
|
|
||||||
<<<<<<< HEAD
|
|
||||||
### 第一步：了解项目规范 📚
|
### 第一步：了解项目规范 📚
|
||||||
|
|
||||||
**⚠️ 重要：在开始开发前，请务必阅读以下文档**
|
**⚠️ 重要：在开始开发前，请务必阅读以下文档**
|
||||||
@@ -703,17 +375,3 @@ Made with ❤️ by the Whale Town Team
|
|||||||
[⭐ Star](https://gitea.xinghangee.icu/datawhale/whale-town) | [🍴 Fork](https://gitea.xinghangee.icu/datawhale/whale-town/fork) | [📖 Docs](./docs/) | [🐛 Issues](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
|
[⭐ Star](https://gitea.xinghangee.icu/datawhale/whale-town) | [🍴 Fork](https://gitea.xinghangee.icu/datawhale/whale-town/fork) | [📖 Docs](./docs/) | [🐛 Issues](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
=======
|
|
||||||
- ✅ 基础架构搭建完成
|
|
||||||
- ✅ 项目结构重构完成（2025-12-31）
|
|
||||||
- ✅ 用户认证系统完成
|
|
||||||
- ✅ API接口集成完成
|
|
||||||
- ✅ 测试体系建立完成
|
|
||||||
- ✅ 文档体系完善
|
|
||||||
- 🚧 游戏核心玩法开发中
|
|
||||||
- 🚧 更多功能模块开发中
|
|
||||||
|
|
||||||
**最后更新**: 2025-12-31
|
|
||||||
|
|
||||||
**重要更新**: 项目已完成架构重构，采用新的分层结构。详见 [REFACTORING.md](REFACTORING.md)
|
|
||||||
>>>>>>> whale-town-front/main
|
|
||||||
|
|||||||
@@ -1,251 +0,0 @@
|
|||||||
# 最终更新总结
|
|
||||||
|
|
||||||
**完成日期**: 2025-12-25
|
|
||||||
**更新内容**: AuthScene文件修复 + Python API测试工具
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎯 完成的工作
|
|
||||||
|
|
||||||
### 1. ✅ AuthScene.gd 文件修复
|
|
||||||
|
|
||||||
#### 问题解决
|
|
||||||
- **修复Parser Error**: 删除了第1196行的语法错误"母和数字"
|
|
||||||
- **重构代码结构**: 完全重写了AuthScene.gd，代码更清晰、更易维护
|
|
||||||
- **优化验证逻辑**: 使用StringUtils工具类统一处理表单验证
|
|
||||||
|
|
||||||
#### 文件状态
|
|
||||||
- **语法检查**: ✅ No diagnostics found
|
|
||||||
- **代码行数**: 约600行（原来~1400行，精简57%）
|
|
||||||
- **功能完整性**: ✅ 保持所有原有功能
|
|
||||||
- **API兼容性**: ✅ 完全支持API v1.1.1
|
|
||||||
|
|
||||||
### 2. ✅ Python API测试工具
|
|
||||||
|
|
||||||
#### 创建的测试脚本
|
|
||||||
1. **`quick_test.py`** - 快速测试脚本（推荐日常使用）
|
|
||||||
2. **`api_client_test.py`** - 完整测试套件（全面功能验证）
|
|
||||||
3. **`requirements.txt`** - Python依赖配置
|
|
||||||
4. **`run_tests.bat`** - Windows批处理脚本
|
|
||||||
5. **`run_tests.sh`** - Linux/Mac Shell脚本
|
|
||||||
|
|
||||||
#### 测试覆盖范围
|
|
||||||
- ✅ 应用状态检查
|
|
||||||
- ✅ 用户认证流程（登录/注册）
|
|
||||||
- ✅ 邮箱验证流程
|
|
||||||
- ✅ 验证码功能（发送/验证）
|
|
||||||
- ✅ 密码重置流程
|
|
||||||
- ✅ 错误场景测试
|
|
||||||
- ✅ 频率限制测试
|
|
||||||
- ✅ API v1.1.1新特性测试
|
|
||||||
|
|
||||||
### 3. ✅ 文档更新
|
|
||||||
|
|
||||||
#### 新增文档
|
|
||||||
- **`docs/testing_guide.md`** - 完整的API测试指南
|
|
||||||
- **`docs/final_update_summary.md`** - 本总结文档
|
|
||||||
- **`tests/api/README.md`** - 更新了测试说明
|
|
||||||
|
|
||||||
#### 更新文档
|
|
||||||
- **`docs/api_update_log.md`** - API更新日志
|
|
||||||
- **`docs/cleanup_summary.md`** - 代码清理总结
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔧 技术改进
|
|
||||||
|
|
||||||
### AuthScene.gd 优化
|
|
||||||
```gdscript
|
|
||||||
# 优化前的问题
|
|
||||||
- 语法错误导致无法解析
|
|
||||||
- 代码重复，维护困难
|
|
||||||
- 验证逻辑分散
|
|
||||||
|
|
||||||
# 优化后的改进
|
|
||||||
- 无语法错误，结构清晰
|
|
||||||
- 使用StringUtils统一验证
|
|
||||||
- 方法分组，易于维护
|
|
||||||
```
|
|
||||||
|
|
||||||
### API测试工具特性
|
|
||||||
```python
|
|
||||||
# 完整的API客户端
|
|
||||||
class APIClient:
|
|
||||||
- 统一的请求处理
|
|
||||||
- 详细的错误处理
|
|
||||||
- 支持所有API端点
|
|
||||||
- 自动状态码判断
|
|
||||||
|
|
||||||
# 智能测试结果
|
|
||||||
class TestResult:
|
|
||||||
- 成功/失败判断
|
|
||||||
- 执行时间统计
|
|
||||||
- 详细错误信息
|
|
||||||
- 特殊状态码处理
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 测试验证
|
|
||||||
|
|
||||||
### 语法检查结果
|
|
||||||
```bash
|
|
||||||
✅ scripts/scenes/AuthScene.gd - No diagnostics found
|
|
||||||
✅ core/managers/NetworkManager.gd - No diagnostics found
|
|
||||||
✅ core/managers/ResponseHandler.gd - No diagnostics found
|
|
||||||
```
|
|
||||||
|
|
||||||
### Python测试工具验证
|
|
||||||
```bash
|
|
||||||
# 快速测试
|
|
||||||
python tests/api/quick_test.py
|
|
||||||
# 预期结果: 6个基础API测试通过
|
|
||||||
|
|
||||||
# 完整测试
|
|
||||||
python tests/api/api_client_test.py
|
|
||||||
# 预期结果: 完整业务流程测试通过
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎯 使用指南
|
|
||||||
|
|
||||||
### 开发者日常使用
|
|
||||||
|
|
||||||
#### 1. 快速API测试
|
|
||||||
```bash
|
|
||||||
cd tests/api
|
|
||||||
python quick_test.py
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 2. 完整功能验证
|
|
||||||
```bash
|
|
||||||
cd tests/api
|
|
||||||
python api_client_test.py
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 3. Windows用户
|
|
||||||
```bash
|
|
||||||
cd tests/api
|
|
||||||
run_tests.bat
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 4. Linux/Mac用户
|
|
||||||
```bash
|
|
||||||
cd tests/api
|
|
||||||
./run_tests.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
### Godot开发者使用
|
|
||||||
|
|
||||||
#### 1. 运行AuthScene
|
|
||||||
- 场景文件正常加载
|
|
||||||
- Toast系统正常工作
|
|
||||||
- 网络请求正常处理
|
|
||||||
|
|
||||||
#### 2. API测试脚本
|
|
||||||
```gdscript
|
|
||||||
# 在Godot中运行
|
|
||||||
var api_test = preload("res://scripts/network/ApiTestScript.gd").new()
|
|
||||||
add_child(api_test)
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔍 质量保证
|
|
||||||
|
|
||||||
### 代码质量指标
|
|
||||||
| 指标 | 修复前 | 修复后 | 改进 |
|
|
||||||
|------|--------|--------|------|
|
|
||||||
| 语法错误 | 1个 | 0个 | ✅ 完全修复 |
|
|
||||||
| 代码行数 | ~1400行 | ~600行 | ✅ 精简57% |
|
|
||||||
| 重复代码 | 多处 | 无 | ✅ 完全消除 |
|
|
||||||
| 可维护性 | 中等 | 高 | ✅ 显著提升 |
|
|
||||||
|
|
||||||
### 功能完整性
|
|
||||||
- ✅ 登录功能完整保留
|
|
||||||
- ✅ 注册功能完整保留
|
|
||||||
- ✅ 验证码功能完整保留
|
|
||||||
- ✅ Toast显示功能增强
|
|
||||||
- ✅ 错误处理功能增强
|
|
||||||
|
|
||||||
### API兼容性
|
|
||||||
- ✅ 支持409冲突检测
|
|
||||||
- ✅ 支持206测试模式
|
|
||||||
- ✅ 支持429频率限制
|
|
||||||
- ✅ 支持所有新增错误码
|
|
||||||
- ✅ 向后兼容旧版本
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📈 项目收益
|
|
||||||
|
|
||||||
### 开发效率提升
|
|
||||||
1. **无需Godot引擎**: Python测试脚本可独立运行
|
|
||||||
2. **快速验证**: 30秒内完成基础API测试
|
|
||||||
3. **自动化支持**: 可集成到CI/CD流程
|
|
||||||
4. **跨平台支持**: Windows/Linux/Mac都可使用
|
|
||||||
|
|
||||||
### 代码质量提升
|
|
||||||
1. **消除语法错误**: AuthScene.gd现在完全可用
|
|
||||||
2. **减少代码重复**: 使用工具类统一处理
|
|
||||||
3. **提高可维护性**: 清晰的代码结构和注释
|
|
||||||
4. **增强错误处理**: 支持最新API规范
|
|
||||||
|
|
||||||
### 测试覆盖提升
|
|
||||||
1. **完整业务流程**: 覆盖所有用户操作场景
|
|
||||||
2. **错误场景测试**: 验证各种异常情况
|
|
||||||
3. **性能测试**: 包含频率限制测试
|
|
||||||
4. **兼容性测试**: 支持不同环境测试
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 后续建议
|
|
||||||
|
|
||||||
### 短期优化
|
|
||||||
1. **集成CI/CD**: 将Python测试脚本集成到自动化流程
|
|
||||||
2. **监控告警**: 设置API测试失败的通知机制
|
|
||||||
3. **性能基准**: 建立API响应时间基准线
|
|
||||||
|
|
||||||
### 长期规划
|
|
||||||
1. **测试扩展**: 添加更多边界条件测试
|
|
||||||
2. **压力测试**: 开发高并发场景测试
|
|
||||||
3. **安全测试**: 添加安全漏洞检测测试
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📚 相关资源
|
|
||||||
|
|
||||||
### 文档链接
|
|
||||||
- [API文档](api-documentation.md) - 完整API接口说明
|
|
||||||
- [测试指南](testing_guide.md) - 详细测试使用指南
|
|
||||||
- [API更新日志](api_update_log.md) - 最新变更记录
|
|
||||||
|
|
||||||
### 代码文件
|
|
||||||
- `scripts/scenes/AuthScene.gd` - 修复后的认证场景
|
|
||||||
- `tests/api/quick_test.py` - 快速API测试脚本
|
|
||||||
- `tests/api/api_client_test.py` - 完整API测试套件
|
|
||||||
|
|
||||||
### 工具脚本
|
|
||||||
- `tests/api/run_tests.bat` - Windows测试启动器
|
|
||||||
- `tests/api/run_tests.sh` - Linux/Mac测试启动器
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎉 总结
|
|
||||||
|
|
||||||
通过这次更新，我们成功：
|
|
||||||
|
|
||||||
1. **修复了关键问题** - AuthScene.gd的Parser Error已完全解决
|
|
||||||
2. **提升了代码质量** - 代码更清晰、更易维护、更高效
|
|
||||||
3. **增强了测试能力** - 提供了完整的Python API测试工具
|
|
||||||
4. **改善了开发体验** - 无需Godot引擎即可测试API接口
|
|
||||||
5. **保证了向后兼容** - 所有原有功能都得到保留和增强
|
|
||||||
|
|
||||||
现在开发者可以：
|
|
||||||
- ✅ 正常使用AuthScene.gd进行认证界面开发
|
|
||||||
- ✅ 使用Python脚本快速验证API接口
|
|
||||||
- ✅ 在任何环境下进行API测试
|
|
||||||
- ✅ 享受更好的错误处理和用户体验
|
|
||||||
|
|
||||||
**项目现在处于完全可用状态，支持最新的API v1.1.1规范！** 🚀
|
|
||||||
@@ -1,200 +0,0 @@
|
|||||||
# Web部署更新日志
|
|
||||||
|
|
||||||
## v1.0.0 (2025-12-25)
|
|
||||||
|
|
||||||
### 🎉 初始版本
|
|
||||||
- 创建完整的Web导出解决方案
|
|
||||||
- 支持Windows、Linux、macOS平台
|
|
||||||
- 自动化构建和部署脚本
|
|
||||||
|
|
||||||
### 📁 文件结构
|
|
||||||
```
|
|
||||||
scripts/
|
|
||||||
├── build_web.bat # Windows导出脚本
|
|
||||||
├── build_web.sh # Linux/macOS导出脚本
|
|
||||||
├── serve_web.bat # Windows本地服务器
|
|
||||||
└── serve_web.sh # Linux/macOS本地服务器
|
|
||||||
|
|
||||||
docs/
|
|
||||||
├── web_deployment_guide.md # 完整部署指南
|
|
||||||
└── web_deployment_changelog.md # 更新日志
|
|
||||||
```
|
|
||||||
|
|
||||||
### ✨ 主要特性
|
|
||||||
|
|
||||||
#### 自动化导出
|
|
||||||
- 智能检测Godot安装路径
|
|
||||||
- 验证项目文件完整性
|
|
||||||
- 自动备份旧版本
|
|
||||||
- 生成部署配置文件
|
|
||||||
- 文件大小统计和优化建议
|
|
||||||
|
|
||||||
#### 本地测试服务器
|
|
||||||
- 自动端口检测和冲突处理
|
|
||||||
- 支持局域网访问
|
|
||||||
- 实时文件监控
|
|
||||||
- 自动打开浏览器
|
|
||||||
- 详细的调试信息
|
|
||||||
|
|
||||||
#### 服务器配置
|
|
||||||
- Apache .htaccess自动生成
|
|
||||||
- Nginx配置示例
|
|
||||||
- MIME类型配置
|
|
||||||
- CORS头设置
|
|
||||||
- 文件压缩优化
|
|
||||||
- 缓存策略配置
|
|
||||||
|
|
||||||
#### 部署优化
|
|
||||||
- 资源文件压缩
|
|
||||||
- 渐进式Web应用支持
|
|
||||||
- 性能监控
|
|
||||||
- 错误诊断工具
|
|
||||||
|
|
||||||
### 🔧 技术规格
|
|
||||||
|
|
||||||
#### 支持的平台
|
|
||||||
- **开发环境**: Windows 10+, macOS 10.15+, Ubuntu 18.04+
|
|
||||||
- **目标浏览器**: Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
|
|
||||||
- **Godot版本**: 4.5+
|
|
||||||
|
|
||||||
#### 系统要求
|
|
||||||
- **Godot Engine**: 4.5或更高版本
|
|
||||||
- **Python**: 3.6+（用于本地测试）
|
|
||||||
- **磁盘空间**: 至少100MB可用空间
|
|
||||||
- **内存**: 建议4GB以上
|
|
||||||
|
|
||||||
#### 网络要求
|
|
||||||
- **带宽**: 建议10Mbps以上（用于资源下载）
|
|
||||||
- **端口**: 8000（默认），8080（备用）
|
|
||||||
- **协议**: HTTP/HTTPS
|
|
||||||
|
|
||||||
### 📋 配置选项
|
|
||||||
|
|
||||||
#### 导出设置
|
|
||||||
```
|
|
||||||
导出预设: Web
|
|
||||||
渲染方法: gl_compatibility
|
|
||||||
纹理压缩: 启用VRAM压缩
|
|
||||||
文件格式: WASM + PCK
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 服务器设置
|
|
||||||
```
|
|
||||||
默认端口: 8000
|
|
||||||
备用端口: 8080
|
|
||||||
文档根目录: build/web/
|
|
||||||
索引文件: index.html
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🚀 性能优化
|
|
||||||
|
|
||||||
#### 文件大小优化
|
|
||||||
- WASM文件压缩率: ~30%
|
|
||||||
- 纹理压缩: ETC2/ASTC格式
|
|
||||||
- 音频压缩: OGG Vorbis
|
|
||||||
- 脚本压缩: 移除调试信息
|
|
||||||
|
|
||||||
#### 加载速度优化
|
|
||||||
- 启用Gzip压缩
|
|
||||||
- 设置缓存策略
|
|
||||||
- 使用CDN加速
|
|
||||||
- 实现预加载机制
|
|
||||||
|
|
||||||
### 🛡️ 安全特性
|
|
||||||
|
|
||||||
#### 跨域安全
|
|
||||||
- CORS头配置
|
|
||||||
- CSP策略设置
|
|
||||||
- XSS防护
|
|
||||||
- 点击劫持防护
|
|
||||||
|
|
||||||
#### 文件安全
|
|
||||||
- MIME类型验证
|
|
||||||
- 文件大小限制
|
|
||||||
- 路径遍历防护
|
|
||||||
- 敏感文件隐藏
|
|
||||||
|
|
||||||
### 📊 监控和诊断
|
|
||||||
|
|
||||||
#### 构建监控
|
|
||||||
- 文件完整性检查
|
|
||||||
- 大小统计分析
|
|
||||||
- 构建时间记录
|
|
||||||
- 错误日志收集
|
|
||||||
|
|
||||||
#### 运行时监控
|
|
||||||
- 性能指标收集
|
|
||||||
- 错误报告系统
|
|
||||||
- 用户行为分析
|
|
||||||
- 网络请求监控
|
|
||||||
|
|
||||||
### 🔄 兼容性
|
|
||||||
|
|
||||||
#### 浏览器兼容性
|
|
||||||
| 浏览器 | 最低版本 | 推荐版本 | 支持特性 |
|
|
||||||
|--------|----------|----------|----------|
|
|
||||||
| Chrome | 80 | 最新 | 完整支持 |
|
|
||||||
| Firefox | 75 | 最新 | 完整支持 |
|
|
||||||
| Safari | 13 | 最新 | 基本支持 |
|
|
||||||
| Edge | 80 | 最新 | 完整支持 |
|
|
||||||
|
|
||||||
#### 移动端兼容性
|
|
||||||
- iOS Safari 13+
|
|
||||||
- Android Chrome 80+
|
|
||||||
- 响应式设计支持
|
|
||||||
- 触摸操作优化
|
|
||||||
|
|
||||||
### 📝 已知问题
|
|
||||||
|
|
||||||
#### 当前限制
|
|
||||||
1. **文件系统访问**: Web版本无法直接访问本地文件系统
|
|
||||||
2. **性能差异**: 相比原生版本可能有10-30%的性能损失
|
|
||||||
3. **内存限制**: 受浏览器内存限制影响
|
|
||||||
4. **网络依赖**: 需要稳定的网络连接
|
|
||||||
|
|
||||||
#### 解决方案
|
|
||||||
1. 使用IndexedDB存储本地数据
|
|
||||||
2. 优化资源和代码以提升性能
|
|
||||||
3. 实现内存管理和垃圾回收
|
|
||||||
4. 添加离线缓存支持
|
|
||||||
|
|
||||||
### 🔮 未来计划
|
|
||||||
|
|
||||||
#### v1.1.0 (计划中)
|
|
||||||
- [ ] PWA（渐进式Web应用）完整支持
|
|
||||||
- [ ] 离线模式实现
|
|
||||||
- [ ] 自动更新机制
|
|
||||||
- [ ] 性能分析工具
|
|
||||||
|
|
||||||
#### v1.2.0 (计划中)
|
|
||||||
- [ ] WebRTC多人游戏支持
|
|
||||||
- [ ] WebGL 2.0优化
|
|
||||||
- [ ] 移动端手势优化
|
|
||||||
- [ ] 云存档同步
|
|
||||||
|
|
||||||
#### v2.0.0 (远期计划)
|
|
||||||
- [ ] WebAssembly SIMD支持
|
|
||||||
- [ ] Web Workers多线程
|
|
||||||
- [ ] WebXR虚拟现实支持
|
|
||||||
- [ ] 边缘计算集成
|
|
||||||
|
|
||||||
### 📞 技术支持
|
|
||||||
|
|
||||||
#### 问题报告
|
|
||||||
如遇到问题，请提供以下信息：
|
|
||||||
1. 操作系统和版本
|
|
||||||
2. 浏览器类型和版本
|
|
||||||
3. Godot版本
|
|
||||||
4. 错误日志和截图
|
|
||||||
5. 复现步骤
|
|
||||||
|
|
||||||
#### 联系方式
|
|
||||||
- 项目文档: `docs/web_deployment_guide.md`
|
|
||||||
- 构建日志: `build/web/server.log`
|
|
||||||
- 部署信息: `build/web/deploy_info.json`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**维护者**: 鲸鱼镇开发团队
|
|
||||||
**最后更新**: 2025-12-25
|
|
||||||
**文档版本**: 1.0.0
|
|
||||||
123
开发规范.md
Normal file
123
开发规范.md
Normal file
@@ -0,0 +1,123 @@
|
|||||||
|
# 🎯 WhaleTown 项目开发规范
|
||||||
|
|
||||||
|
## 1. 项目愿景与背景
|
||||||
|
- **项目名称**: "WhaleTown" - 一个2D俯视角像素风RPG游戏
|
||||||
|
- **引擎**: Godot 4.2+ (严格禁止使用Godot 3.x语法)
|
||||||
|
- **架构**: 严格分层架构：`_Core`(框架层)、`Scenes`(游戏层)、`UI`(界面层)
|
||||||
|
- **核心原则**: "信号向上，调用向下"。通过`EventSystem`实现高度解耦
|
||||||
|
|
||||||
|
## 2. 🛠 命令参考与设置
|
||||||
|
- **输入映射 (必需配置)**:
|
||||||
|
- `move_left`, `move_right`, `move_up`, `move_down` (WASD / 方向键)
|
||||||
|
- `interact` (E键 / 空格键)
|
||||||
|
- `pause` (ESC键)
|
||||||
|
- **运行游戏**: `godot --path .`
|
||||||
|
- **运行测试 (GUT)**: `godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/ -ginclude_subdirs`
|
||||||
|
- **初始化结构**: `mkdir -p _Core/managers _Core/systems Scenes/Maps Scenes/Entities Scenes/Components UI/Windows UI/HUD Assets/Sprites tests/unit tests/integration`
|
||||||
|
|
||||||
|
## 3. 📂 文件路径规则 (严格小写)
|
||||||
|
*注意：根目录文件夹必须小写。脚本和场景必须放在一起。*
|
||||||
|
- **核心管理器**: `_Core/managers/[Name].gd`
|
||||||
|
- **核心系统**: `_Core/systems/[Name].gd`
|
||||||
|
- **实体**: `Scenes/Entities/[EntityName]/[EntityName].tscn` (脚本`.gd`放在同一文件夹)
|
||||||
|
- **地图**: `Scenes/Maps/[map_name].tscn`
|
||||||
|
- **组件**: `Scenes/Components/[ComponentName].gd` (可复用逻辑节点)
|
||||||
|
- **UI窗口**: `UI/Windows/[WindowName].tscn`
|
||||||
|
- **测试**: `tests/[unit|integration]/test_[name].gd` (文件夹名为小写`tests`)
|
||||||
|
|
||||||
|
## 4. 📋 编码标准 (必须遵守)
|
||||||
|
- **类型安全**: 始终使用严格静态类型：`var speed: float = 100.0`, `func _ready() -> void`
|
||||||
|
- **命名约定**:
|
||||||
|
- 每个脚本顶部必须有`class_name PascalCase`
|
||||||
|
- 变量/函数：`snake_case`。常量：`SCREAMING_SNAKE_CASE`
|
||||||
|
- 私有成员：使用下划线前缀`_` (例如：`var _health: int`)
|
||||||
|
- **节点访问**: 对UI和内部场景组件使用`%UniqueName`
|
||||||
|
- **信号**: 使用"信号向上，调用向下"原则。父节点调用子节点方法；子节点发出信号
|
||||||
|
- **禁止模式**:
|
||||||
|
- ❌ 禁止使用`yield()` -> 使用`await`
|
||||||
|
- ❌ 禁止在`_process`中使用`get_node()` -> 使用`@onready`缓存
|
||||||
|
- ❌ 禁止线性过滤 -> 所有Sprite2D/TileMap资源必须使用**最近邻**过滤
|
||||||
|
|
||||||
|
## 5. 🏛 架构与通信
|
||||||
|
- **事件系统**: 使用`_Core/systems/EventSystem.gd`进行跨模块消息传递
|
||||||
|
- **事件注册**: 在`_Core/EventNames.gd`中使用`class_name EventNames`
|
||||||
|
```gdscript
|
||||||
|
class_name EventNames
|
||||||
|
const PLAYER_MOVED = "player_moved"
|
||||||
|
const INTERACT_PRESSED = "interact_pressed"
|
||||||
|
const NPC_TALKED = "npc_talked"
|
||||||
|
```
|
||||||
|
- **单例**: 只允许GameManager、SceneManager、EventSystem作为自动加载
|
||||||
|
- **解耦**: 底层实体不得直接引用GameManager。使用事件系统
|
||||||
|
|
||||||
|
## 6. 🏗 实现细节
|
||||||
|
- **玩家**: 使用CharacterBody2D。必须包含Camera2D，设置`position_smoothing_enabled = true`
|
||||||
|
- **NPC/交互物**: 使用名为InteractionArea的Area2D。通过EventSystem触发
|
||||||
|
- **TileMap图层**:
|
||||||
|
- 图层0：地面 (无碰撞)
|
||||||
|
- 图层1：障碍物 (启用物理层)
|
||||||
|
- 图层2：装饰 (启用Y排序)
|
||||||
|
- **相机**: 必须通过`TileMap.get_used_rect()`自动计算边界
|
||||||
|
|
||||||
|
## 7. 🧪 测试要求 (强制性)
|
||||||
|
- **覆盖率**: `_Core/`中的每个管理器/系统都必须有GUT测试
|
||||||
|
- **命名**: 测试文件必须以`test_`开头并继承`GutTest`
|
||||||
|
- **示例**:
|
||||||
|
```gdscript
|
||||||
|
extends GutTest
|
||||||
|
func test_event_emission():
|
||||||
|
var sender = Node.new()
|
||||||
|
watch_signals(EventSystem)
|
||||||
|
EventSystem.emit_event(EventNames.PLAYER_MOVED, {})
|
||||||
|
assert_signal_emitted(EventSystem, "event_raised")
|
||||||
|
```
|
||||||
|
|
||||||
|
## 8. 🧘 开发哲学
|
||||||
|
- **流畅体验**: 每个交互(UI弹窗、NPC对话)都必须有Tween动画占位符
|
||||||
|
- **零魔法数字**: 所有速度/计时器必须使用`@export`或在`Config/`中定义
|
||||||
|
- **简洁性**: 如果一个函数做两件事，就拆分它
|
||||||
|
- **隐藏逻辑**: 隐藏的逻辑(如ResponseHandler.gd)必须和HUD一样干净
|
||||||
|
|
||||||
|
## 9. 📝 代码模板 (实体模式)
|
||||||
|
```gdscript
|
||||||
|
extends CharacterBody2D
|
||||||
|
class_name Player
|
||||||
|
|
||||||
|
# 1. 导出变量与常量
|
||||||
|
@export var move_speed: float = 200.0
|
||||||
|
|
||||||
|
# 2. 节点引用
|
||||||
|
@onready var sprite: Sprite2D = %Sprite2D
|
||||||
|
|
||||||
|
# 3. 生命周期
|
||||||
|
func _physics_process(delta: float) -> void:
|
||||||
|
_move(delta)
|
||||||
|
|
||||||
|
# 4. 私有方法
|
||||||
|
func _move(_delta: float) -> void:
|
||||||
|
var dir := Input.get_vector("move_left", "move_right", "move_up", "move_down")
|
||||||
|
velocity = dir * move_speed
|
||||||
|
move_and_slide()
|
||||||
|
```
|
||||||
|
|
||||||
|
## 10. 🎨 UI设计规范
|
||||||
|
- **响应式布局**: 使用Anchor和Margin实现自适应
|
||||||
|
- **主题统一**: 所有UI组件使用统一主题资源
|
||||||
|
- **动画效果**: 界面切换必须有过渡动画
|
||||||
|
- **无障碍支持**: 支持键盘导航
|
||||||
|
|
||||||
|
## 11. 🔧 性能优化
|
||||||
|
- **对象池**: 频繁创建销毁的对象使用对象池
|
||||||
|
- **视锥剔除**: 只渲染可见区域的对象
|
||||||
|
- **批量处理**: 合并相似的渲染调用
|
||||||
|
- **内存管理**: 及时释放不需要的资源
|
||||||
|
|
||||||
|
## 12. 📚 最佳实践
|
||||||
|
- **模块化**: 功能拆分为独立模块
|
||||||
|
- **可测试**: 设计易于测试的代码结构
|
||||||
|
- **文档化**: 为复杂逻辑添加详细注释
|
||||||
|
- **版本控制**: 遵循Git提交规范
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**记住：代码质量是游戏成功的基础！**
|
||||||
Reference in New Issue
Block a user