datawhale/whale-town
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

创建新工程

Browse Source
This commit is contained in:
moyin
2025-12-05 19:00:14 +08:00
commit ff4fa5fffd
227 changed files with 32804 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

634
.kiro/specs/character-appearance-customization/design.md Normal file
View File

@@ -0,0 +1,634 @@
# 角色外观自定义系统设计文档
## 概述
本设计文档描述了为现有 Godot AI 小镇游戏添加角色外观自定义功能的完整方案。该系统将在现有角色创建流程的基础上，添加一个专门的外观自定义界面，允许用户自定义角色的头部、身体、脚部颜色，并通过流畅的UI动效提升用户体验。
### 技术栈
- **游戏引擎**: Godot 4.x
- **编程语言**: GDScript
- **UI框架**: Godot Control 节点系统
- **动画系统**: Godot Tween 和 AnimationPlayer
- **数据格式**: Dictionary (GDScript 原生)
- **颜色系统**: Godot Color 类
## 架构
### 整体架构
角色外观自定义系统采用模块化设计，与现有的角色创建系统集成：
```
┌─────────────────────────────────────────┐
│ 角色创建流程 (CharacterCreation) │
├─────────────────────────────────────────┤
│ 1. 默认外观生成 │
│ 2. 角色名称输入 │
│ 3. 自定义外观按钮 │
│ 4. 创建角色按钮 │
└─────────────────────────────────────────┘
↓ 点击自定义外观
┌─────────────────────────────────────────┐
│ 外观自定义界面 (AppearanceCustomizer) │
├─────────────────────────────────────────┤
│ ┌─────────────────────────────────────┐ │
│ │ 头部颜色调整区域 │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 颜色选择器 │ │ 预设颜色 │ │ │
│ │ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────┘ │
│ ┌─────────────────────────────────────┐ │
│ │ 身体颜色调整区域 │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 颜色选择器 │ │ 预设颜色 │ │ │
│ │ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────┘ │
│ ┌─────────────────────────────────────┐ │
│ │ 脚部颜色调整区域 │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 颜色选择器 │ │ 预设颜色 │ │ │
│ │ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────┘ │
│ ┌─────────────────────────────────────┐ │
│ │ 角色预览区域 │ │
│ │ ┌─────────────────────────────┐ │ │
│ │ │ 实时预览显示 │ │ │
│ │ └─────────────────────────────┘ │ │
│ └─────────────────────────────────────┘ │
│ ┌─────────────────────────────────────┐ │
│ │ 操作按钮区域 │ │
│ │ [返回] [重置] [随机生成] [保存] │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘
↓ 点击返回/保存
┌─────────────────────────────────────────┐
│ 角色创建流程 (更新后) │
├─────────────────────────────────────────┤
│ 1. 显示自定义外观预览 │
│ 2. 角色名称输入 │
│ 3. 创建角色按钮 (应用自定义外观) │
└─────────────────────────────────────────┘
```
### 组件架构
系统主要包含以下核心组件：
```
AppearanceCustomizer (主控制器)
├─ DefaultAppearanceGenerator (默认外观生成器)
├─ ColorAdjustmentPanel (颜色调整面板)
│ ├─ HeadColorAdjuster (头部颜色调整器)
│ ├─ BodyColorAdjuster (身体颜色调整器)
│ └─ FootColorAdjuster (脚部颜色调整器)
├─ AppearancePreview (外观预览器)
├─ UIAnimationController (UI动画控制器)
└─ AppearanceDataManager (外观数据管理器)
```
## 组件和接口
### 1. 默认外观生成器 (DefaultAppearanceGenerator)
**职责**: 为新角色生成协调的默认外观
**接口**:
```gdscript
class_name DefaultAppearanceGenerator
static func generate_default_appearance() -> Dictionary
static func generate_coordinated_colors() -> Dictionary
static func get_fallback_appearance() -> Dictionary
static func validate_appearance_data(appearance: Dictionary) -> bool
```
**生成规则**:
- 头部颜色：使用肤色色调范围
- 身体颜色：使用服装色调范围，与头部形成对比
- 脚部颜色：使用鞋子色调范围，与身体协调
- 确保颜色对比度适中，视觉效果和谐
### 2. 颜色调整器 (ColorAdjuster)
**职责**: 处理单个身体部位的颜色调整
**接口**:
```gdscript
class_name ColorAdjuster extends Control
signal color_changed(new_color: Color)
var current_color: Color
var preset_colors: Array[Color]
var color_picker: ColorPicker
var preset_buttons: Array[Button]
func set_color(color: Color) -> void
func get_color() -> Color
func setup_presets(colors: Array[Color]) -> void
func reset_to_default() -> void
```
**预设颜色方案**:
- 头部：5种肤色选项
- 身体：8种服装颜色选项
- 脚部：6种鞋子颜色选项
### 3. 外观预览器 (AppearancePreview)
**职责**: 实时显示角色外观预览
**接口**:
```gdscript
class_name AppearancePreview extends Control
var character_sprite: CharacterSprite
var head_sprite: Sprite2D
var body_sprite: Sprite2D
var foot_sprite: Sprite2D
func update_appearance(appearance_data: Dictionary) -> void
func set_head_color(color: Color) -> void
func set_body_color(color: Color) -> void
func set_foot_color(color: Color) -> void
func animate_color_change(part: String, color: Color) -> void
```
**预览特性**:
- 实时颜色更新（延迟 < 100ms）
- 平滑的颜色过渡动画
- 支持不同身体部位的独立渲染
### 4. UI动画控制器 (UIAnimationController)
**职责**: 管理界面切换和元素动画
**接口**:
```gdscript
class_name UIAnimationController
static func hide_creation_elements(elements: Array[Control], duration: float = 0.5) -> void
static func show_creation_elements(elements: Array[Control], duration: float = 0.5) -> void
static func slide_in_customizer(customizer: Control, direction: String = "right") -> void
static func slide_out_customizer(customizer: Control, direction: String = "left") -> void
static func fade_transition(from_scene: Control, to_scene: Control) -> void
```
**动画类型**:
- 淡出动画：透明度从1.0到0.0
- 滑动动画：位置偏移动画
- 缩放动画：大小变化动画
- 组合动画：多种效果结合
### 5. 外观数据管理器 (AppearanceDataManager)
**职责**: 管理外观数据的存储、加载和验证
**接口**:
```gdscript
class_name AppearanceDataManager
static func create_appearance_data(head: Color, body: Color, foot: Color) -> Dictionary
static func validate_appearance_data(data: Dictionary) -> bool
static func serialize_appearance(data: Dictionary) -> String
static func deserialize_appearance(json_str: String) -> Dictionary
static func merge_with_defaults(custom_data: Dictionary) -> Dictionary
```
**数据结构**:
```gdscript
{
"head_color": "#F5DEB3", # 头部颜色 (十六进制)
"body_color": "#4169E1", # 身体颜色
"foot_color": "#8B4513", # 脚部颜色
"created_at": 1234567890, # 创建时间戳
"version": "1.0" # 数据版本
}
```
## 数据模型
### 外观数据结构
```gdscript
# 完整的外观数据模型
{
"appearance": {
"head_color": "#F5DEB3",
"body_color": "#4169E1",
"foot_color": "#8B4513",
"style": "default",
"created_at": 1234567890,
"version": "1.0"
},
"metadata": {
"is_custom": true,
"last_modified": 1234567890,
"modification_count": 3
}
}
```
### 颜色预设数据
```gdscript
# 预设颜色方案
const COLOR_PRESETS = {
"head": [
Color("#F5DEB3"), # 浅肤色
Color("#DEB887"), # 中等肤色
Color("#D2B48C"), # 小麦色
Color("#CD853F"), # 深肤色
Color("#A0522D") # 棕色肤色
],
"body": [
Color("#FF6B6B"), # 红色
Color("#4ECDC4"), # 青色
Color("#45B7D1"), # 蓝色
Color("#96CEB4"), # 绿色
Color("#FFEAA7"), # 黄色
Color("#DDA0DD"), # 紫色
Color("#F0E68C"), # 卡其色
Color("#FFB6C1") # 粉色
],
"foot": [
Color("#8B4513"), # 棕色
Color("#000000"), # 黑色
Color("#FFFFFF"), # 白色
Color("#FF0000"), # 红色
Color("#0000FF"), # 蓝色
Color("#008000") # 绿色
]
}
```
## 正确性属性
*属性是一个特征或行为，应该在系统的所有有效执行中保持为真——本质上是关于系统应该做什么的正式陈述。属性作为人类可读规范和机器可验证正确性保证之间的桥梁。*
### 属性反思
在编写正确性属性之前，我需要识别和消除冗余：
**识别的冗余属性**:
1. 属性3、4、5（头部、身体、脚部颜色调整控件）可以合并为一个通用属性
2. 属性6、7（外观数据保存和预览更新）在逻辑上相关，可以合并
3. 属性8、9（重置和随机生成按钮存在性）可以合并为操作按钮完整性属性
**合并后的属性**:
- 将3个独立的颜色调整属性合并为"颜色调整控件完整性"
- 将数据保存和预览更新合并为"外观数据一致性"
- 将按钮存在性检查合并为"操作按钮完整性"
### 属性 1: 默认外观生成完整性
*对于任意*角色创建请求，系统应该生成包含头部、身体、脚部颜色的完整外观数据
**验证需求: 1.1, 1.3**
### 属性 2: 外观预览实时更新
*对于任意*外观数据的修改，角色预览应该在100毫秒内反映这些变化
**验证需求: 1.2, 3.5, 6.3**
### 属性 3: 界面切换动画触发
*对于任意*自定义外观按钮的点击操作，系统应该触发界面切换动画并在0.5秒内完成
**验证需求: 2.1, 2.3**
### 属性 4: UI元素动画隐藏
*对于任意*界面切换操作，创建角色按钮和角色名称输入框应该通过动画被隐藏
**验证需求: 2.2**
### 属性 5: 自定义场景正确加载
*对于任意*隐藏动画完成事件，系统应该正确加载并显示角色外观自定义场景
**验证需求: 2.4**
### 属性 6: 颜色调整控件完整性
*对于任意*自定义界面的加载，应该显示头部、身体、脚部的独立颜色调整控件
**验证需求: 3.1, 3.2, 3.3, 3.4**
### 属性 7: 返回按钮规范性
*对于任意*自定义界面，返回按钮应该显示文字"返回"且尺寸满足最小触摸目标要求（44x44像素）
**验证需求: 4.1, 4.2, 4.3, 4.5**
### 属性 8: 外观数据一致性
*对于任意*外观自定义操作，点击返回后角色创建界面的预览应该显示与自定义界面相同的外观
**验证需求: 5.1, 5.2**
### 属性 9: 角色创建外观应用
*对于任意*包含自定义外观的角色创建操作，创建的角色应该在游戏中显示相同的外观
**验证需求: 5.3, 5.4**
### 属性 10: 外观数据序列化往返
*对于任意*外观数据，序列化后再反序列化应该得到等价的数据对象
**验证需求: 5.5**
### 属性 11: 错误处理友好性
*对于任意*操作错误情况，系统应该显示用户友好的错误提示信息
**验证需求: 6.4**
### 属性 12: 移动设备适配性
*对于任意*移动设备尺寸，界面中的按钮应该满足最小触摸目标要求（44x44像素）
**验证需求: 6.5**
### 属性 13: 系统扩展性
*对于任意*新增的颜色调整控件，系统应该能够动态集成并正常工作
**验证需求: 7.2**
### 属性 14: 数据结构扩展性
*对于任意*外观数据结构的新增字段，系统应该能够正确处理而不影响现有功能
**验证需求: 7.3**
### 属性 15: 渲染系统灵活性
*对于任意*类型的外观元素，预览系统应该能够正确渲染显示
**验证需求: 7.4**
### 属性 16: 操作按钮完整性
*对于任意*自定义界面的显示，应该提供重置和随机生成按钮
**验证需求: 8.1, 8.3**
### 属性 17: 重置功能正确性
*对于任意*外观自定义状态，点击重置按钮应该将所有设置恢复到进入界面时的初始状态
**验证需求: 8.2**
### 属性 18: 随机生成功能完整性
*对于任意*随机生成操作，应该为所有身体部位生成颜色并立即更新预览
**验证需求: 8.4, 8.5**
## 错误处理
### 外观生成错误
**默认外观生成失败**:
- 使用预设的备用外观方案
- 记录错误日志用于调试
- 显示友好的错误提示
**颜色数据无效**:
- 验证颜色格式（十六进制）
- 使用默认颜色替换无效值
- 提示用户重新选择
### UI交互错误
**界面切换失败**:
- 回退到上一个稳定状态
- 显示错误提示信息
- 提供重试选项
**动画执行错误**:
- 跳过动画直接切换状态
- 确保功能正常可用
- 记录性能相关信息
### 数据持久化错误
**外观数据保存失败**:
- 保持当前界面状态
- 显示保存失败提示
- 提供重新保存选项
**数据序列化错误**:
- 使用备用序列化方案
- 记录详细错误信息
- 确保数据不丢失
## 测试策略
### 单元测试
使用 Godot 的 GUT (Godot Unit Test) 框架进行单元测试。
**测试覆盖范围**:
- 默认外观生成逻辑
- 颜色调整器功能
- 外观数据序列化/反序列化
- UI动画控制器
**示例测试**:
```gdscript
# test_default_appearance_generator.gd
extends GutTest
func test_generate_default_appearance():
var appearance = DefaultAppearanceGenerator.generate_default_appearance()
assert_true(appearance.has("head_color"))
assert_true(appearance.has("body_color"))
assert_true(appearance.has("foot_color"))
assert_true(DefaultAppearanceGenerator.validate_appearance_data(appearance))
func test_fallback_appearance():
var fallback = DefaultAppearanceGenerator.get_fallback_appearance()
assert_true(DefaultAppearanceGenerator.validate_appearance_data(fallback))
```
### 属性基础测试
使用 GDScript 实现的属性测试框架。
**测试库**: 自定义实现的 PropertyTester 类
**测试配置**: 每个属性测试至少运行 100 次迭代
**测试标注格式**: `# Feature: character-appearance-customization, Property X: [属性描述]`
**属性测试覆盖**:
1. **属性 1: 默认外观生成完整性**
- 生成多个随机角色创建请求
- 验证每次都生成完整的外观数据
2. **属性 2: 外观预览实时更新**
- 生成随机外观修改操作
- 测量预览更新的响应时间
3. **属性 10: 外观数据序列化往返**
- 生成随机外观数据
- 验证序列化往返的数据一致性
**示例属性测试**:
```gdscript
# test_appearance_properties.gd
extends GutTest
# Feature: character-appearance-customization, Property 1: 默认外观生成完整性
func test_property_default_appearance_completeness():
for i in range(100):
var appearance = DefaultAppearanceGenerator.generate_default_appearance()
assert_true(appearance.has("head_color"), "应该包含头部颜色")
assert_true(appearance.has("body_color"), "应该包含身体颜色")
assert_true(appearance.has("foot_color"), "应该包含脚部颜色")
assert_true(DefaultAppearanceGenerator.validate_appearance_data(appearance),
"生成的外观数据应该有效")
# Feature: character-appearance-customization, Property 10: 外观数据序列化往返
func test_property_appearance_serialization_roundtrip():
for i in range(100):
var original_data = generate_random_appearance_data()
var serialized = AppearanceDataManager.serialize_appearance(original_data)
var deserialized = AppearanceDataManager.deserialize_appearance(serialized)
assert_eq_deep(deserialized, original_data,
"序列化往返应该保持数据一致性")
func generate_random_appearance_data() -> Dictionary:
return {
"head_color": "#%06X" % (randi() % 0xFFFFFF),
"body_color": "#%06X" % (randi() % 0xFFFFFF),
"foot_color": "#%06X" % (randi() % 0xFFFFFF),
"created_at": Time.get_unix_time_from_system(),
"version": "1.0"
}
```
### 集成测试
**UI集成测试**:
- 测试完整的外观自定义流程
- 验证界面切换的正确性
- 检查动画效果的执行
**数据集成测试**:
- 测试外观数据在不同组件间的传递
- 验证预览与实际角色的一致性
- 检查数据持久化的完整性
### 用户体验测试
**响应时间测试**:
- 测试颜色调整的响应延迟
- 目标: 预览更新 < 100ms
**动画流畅性测试**:
- 测试界面切换动画的帧率
- 目标: 保持 30+ FPS
**触摸友好性测试**:
- 验证移动设备上的按钮尺寸
- 目标: 最小触摸目标 44x44 像素
## 实现细节
### 界面布局设计
**自定义界面布局**:
```
┌─────────────────────────────────────────┐
│ [返回] 角色外观自定义 │
├─────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────┐ │
│ │ 角色预览区域 │ │
│ │ ┌─────────────────────────────┐ │ │
│ │ │ [角色预览图像] │ │ │
│ │ └─────────────────────────────┘ │ │
│ └─────────────────────────────────────┘ │
│ │
│ 头部颜色: │
│ ┌───┐┌───┐┌───┐┌───┐┌───┐ [颜色选择器] │
│ │ ● ││ ● ││ ● ││ ● ││ ● │ │
│ └───┘└───┘└───┘└───┘└───┘ │
│ │
│ 身体颜色: │
│ ┌───┐┌───┐┌───┐┌───┐┌───┐ [颜色选择器] │
│ │ ● ││ ● ││ ● ││ ● ││ ● │ │
│ └───┘└───┘└───┘└───┘└───┘ │
│ │
│ 脚部颜色: │
│ ┌───┐┌───┐┌───┐┌───┐┌───┐ [颜色选择器] │
│ │ ● ││ ● ││ ● ││ ● ││ ● │ │
│ └───┘└───┘└───┘└───┘└───┘ │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 重置 │ │ 随机生成 │ │ 保存 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────┘
```
### 动画时序设计
**界面切换动画序列**:
1. 用户点击"自定义外观"按钮 (0ms)
2. 开始淡出动画：创建按钮和名称输入框 (0-300ms)
3. 开始滑入动画：自定义界面从右侧滑入 (200-500ms)
4. 完成所有动画，自定义界面完全显示 (500ms)
**颜色更新动画**:
1. 用户选择新颜色 (0ms)
2. 触发颜色变化事件 (0-10ms)
3. 开始预览更新动画 (10-60ms)
4. 完成颜色过渡效果 (60-100ms)
### 性能优化
**渲染优化**:
- 使用对象池管理颜色按钮
- 延迟加载颜色选择器
- 缓存预览渲染结果
**内存优化**:
- 及时释放未使用的UI元素
- 使用弱引用避免循环引用
- 压缩颜色预设数据
**响应性优化**:
- 异步处理颜色计算
- 使用防抖机制减少频繁更新
- 优先处理用户交互事件
## 扩展性考虑
### 未来功能预留
**更多自定义选项**:
- 发型选择
- 服装样式
- 配饰系统
- 表情自定义
**高级功能**:
- 外观模板保存/加载
- 社区外观分享
- AI辅助外观生成
- 外观历史记录
### 数据结构扩展
**版本化数据格式**:
```gdscript
{
"version": "2.0",
"appearance": {
"head": {
"color": "#F5DEB3",
"style": "default",
"accessories": []
},
"body": {
"color": "#4169E1",
"clothing": "shirt",
"pattern": "solid"
},
"foot": {
"color": "#8B4513",
"shoe_type": "sneakers"
}
},
"metadata": {
"created_at": 1234567890,
"last_modified": 1234567890,
"tags": ["custom", "colorful"]
}
}
```
### API设计
**外观系统API**:
```gdscript
# 外观管理器接口
class_name AppearanceManager
static func create_customizer() -> AppearanceCustomizer
static func register_part_adjuster(part: String, adjuster: ColorAdjuster) -> void
static func get_supported_parts() -> Array[String]
static func validate_appearance_data(data: Dictionary, version: String) -> bool
static func migrate_appearance_data(data: Dictionary, from_version: String, to_version: String) -> Dictionary
```
这种设计确保了系统的可扩展性，为未来添加更多自定义功能提供了坚实的基础。