# LitterPutting

**Repository Path**: zuoo/litter-putting

## Basic Information

- **Project Name**: LitterPutting
- **Description**: 这是一个给小朋友的安卓App，主要是提供一个技能树用于可视化小朋友的成长。此外也提供一些满足小工具，例如三维太阳系、每周一山记录，后续敬请期待。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-23
- **Last Updated**: 2026-02-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 儿童成长助手 🌟

一个专为6岁儿童设计的成长记录和教育应用，使用Qt、QML和C++开发，支持PC和Android平台。

## 🖼️ 界面预览

### 截图
- 主界面总览：![alt text](docs/imgs/主界面.png)
- 技能树画布：![alt text](docs/imgs/运动-技能树.png)
- 太阳系探索：![alt text](docs/imgs/太阳系.png)
- 地球探索：![alt text](docs/imgs/地球.png)
- 身高记录：![alt text](docs/imgs/身高记录.png)
- 身高统计：![alt text](docs/imgs/身高统计.png)
- 头像：![alt text](docs/imgs/头像栏.png)
- 玩家资料与勋章：![alt text](docs/imgs/勋章墙.png)

### 视频演示
- 功能演示视频：待提供

## 📥 APK 下载
- 网盘地址：我用夸克网盘给你分享了「android-build-appLitterPutting-release-signed.apk」，点击链接或复制整段内容，打开「夸克APP」即可获取。
  链接：https://pan.quark.cn/s/256a16928712
- 提取码：无

## 🎯 核心功能

### 🔦 天黑请闭眼 (迷宫探索)
- **黑暗迷宫玩法**：
  - 视野限制：只能看到角色周围有限的区域
  - **全新移动系统**：
    - **极速响应**：单击方向键立即移动，无冷却时间
    - **长按加速**：长按方向键以 3格/秒 的速度快速移动
  - **角色调整**：角色体积缩小为通道的 2/3，避免遮挡视野
  - **关卡升级**：全面扩展关卡面积和难度，修复死局，增加挑战性
- **🎒 道具系统**：
  - **强力火把**：永久增加视野范围
  - **照明弹**：
    - **像素风瞄准**：单击道具栏照明弹，角色身上出现红色像素箭头指示方向
    - **双击发射**：双击屏幕发射照明弹，沿途照亮飞行轨迹（持续3秒）
    - **战术照明**：照明弹以0.5格/秒的速度飞行，并在终点爆炸照亮大范围
    - **演示动画**：![天黑请闭眼-照明弹](docs/imgs/天黑请闭眼-照明弹.gif)
  - **黄金罗盘**：虽然没用但很好看（收藏品）
  - **神秘地图**：并不会显示地图（收藏品）

### 🌳 智能技能树系统
- **多技能树管理**：支持创建、重命名、删除多个技能树
- **可视化技能图谱**：树状结构清晰展示技能层级关系
- **导入/导出技能树**：支持JSON格式备份与迁移
- **⭐⭐⭐ 三星评价系统**（最新）：
  - 完成技能时可选择1-3星评价完成质量
  - 精美的三星选择对话框，点击星星有动画特效
  - 已完成节点右上角显示星级
  - 支持重新挑战提高星级
  - 星级数据自动保存和云同步
- **智能自动排列算法**：
  - 采用自底向上的树形布局算法
  - 删除节点后自动重排，保持美观对称
  - 平滑动画过渡效果
- **右键/长按重命名**：技能节点和技能树均支持快速重命名
- **完成度跟踪**：可视化标记已完成技能，彩色进度显示
- **难度等级系统**：1-3星难度标识
- **游戏化设计**：技能解锁、进度跟踪、成就系统

### 🌞 太阳系探索
- **真实天文模拟**：基于J2000.0历元的天文算法
  - 行星位置实时计算
  - 公转周期：88天(水星) ~ 60190天(海王星)
  - 自转动画：所有行星带自转效果
  - 月球公转：27.3天周期，正确绕地球运转
- **精美视觉效果**：
  - 行星3D渐变纹理(高光→主色→阴影)
  - 地球：真实大陆轮廓(Canvas绘制)+ 晨昏线 + 月球
  - 木星：气态斑点纹理
  - 土星：倾斜光环
  - 动态云层效果
- **交互控制**：
  - 时间速度调节：0.1-20天/秒
  - 鼠标滚轮缩放：0.3x - 5x
  - 左键拖动视图
  - 暂停/播放/重置
- **🌍 双击地球 - 高清地球详细视图**：
  - **支持纹理贴图**：可加载NASA/Solar System Scope的高清地球纹理
    - 自动检测纹理资源，无纹理时使用Canvas绘制
    - 支持2k/4k高分辨率卫星图片
    - 独立旋转的动态云层效果
    - 详见 `images/README.md` 获取纹理下载指南
  - 6大洲轮廓（亚洲、非洲、欧洲、北美、南美、澳洲）
  - 海洋、陆地、云层细节
  - 完整天文数据展示
- **NASA官网直达**：一键访问NASA Eyes on the Solar System

### 🏔️ 每周一山登山记录
- **地图展示**：使用Qt Location显示登山地点
- **记录管理**：添加、编辑、删除登山记录
- **详细信息**：山名、地点、海拔、距离、时长、天气、难度
- **统计功能**：总记录数、总距离、总时长统计

### 👤 玩家系统
- **个性化头像**：40+种Emoji头像选择
- **昵称自定义**：点击即可修改玩家昵称
- **成就追踪**：积分和完成技能数实时统计
- **数据持久化**：自动保存玩家信息
- **美化界面**：
  - 彩虹渐变导航栏
  - 浮动云朵动画 ☁️
  - Emoji按钮图标 ✨🗑️✅
  - 儿童友好配色方案

### ☁️ 云同步功能
- **Gitee云端存储**：技能树数据自动同步到Gitee仓库，需要自己创建云同步的仓库
- **跨设备同步**：Windows和Android设备数据实时同步
- **自动化操作**：启动时拉取、修改时上传，无需手动操作
- **安全加密**：HTTPS传输，Token本地存储
- **冲突检测**：启动和退出时智能检测数据冲突

## 💻 技术架构

### 开发环境
- **Qt 6.9+**: 跨平台应用框架
- **C++17**: 后端逻辑和数据处理
- **QML**: 声明式UI和交互
- **CMake**: 构建系统
- **QSettings**: 数据持久化

### 核心组件
**C++ Models:**
- `SkillModel`: 技能树数据模型，实现智能排列算法
- `SolarSystemModel`: 太阳系天文计算模型
- `MountainRecordModel`: 登山记录管理模型
- `PlayerModel`: 玩家数据模型

**QML Views:**
- `AppMain.qml`: 主界面框架
- `SkillTreeView.qml`: 技能树可视化界面
- `SolarSystemView.qml`: 太阳系动画界面
- `MountainView.qml`: 登山记录界面
- `PlayerProfilePanel.qml`: 玩家信息面板

### 关键技术特性
- **Canvas绘制**：地球大陆轮廓、技能树连线
- **属性绑定动画**：Behavior + NumberAnimation
- **模型视图分离**：QAbstractListModel + Repeater
- **天文算法**：简化的Keplerian轨道模型
- **触摸优化**：PC/Android双平台交互支持

## 📦 安装和运行

### 环境要求
- Qt 6.9.2 或更高版本
- CMake 3.16 或更高版本
- MinGW/MSVC (Windows) 或 GCC/Clang (Linux/Mac)
- Android SDK 和 NDK (用于Android构建)
- C++17 编译器

### PC端构建步骤
```bash
# 克隆项目
git clone <repository-url>
cd LitterPutting

# 使用Qt Creator打开CMakeLists.txt
# 或者命令行构建：
mkdir build && cd build
cmake ..
cmake --build .

# 运行
./appLitterPutting  # Linux/Mac
appLitterPutting.exe  # Windows
```

### Android构建
1. 在Qt Creator中打开项目
2. 选择Android Kit
3. 配置Android SDK/NDK路径
4. 点击运行/构建APK

## 🎮 使用说明

### 技能树操作
1. **创建技能树**：点击"✨ 新建技能树"按钮
2. **切换技能树**：顶部下拉选择当前技能树
3. **添加技能**：右击或长按节点选择"添加子技能/关卡"
4. **重命名**：
   - 节点：右击/长按节点菜单选择"重命名"
   - 技能树：画布空白处右击/长按菜单选择"重命名当前技能树"
5. **完成标记**：点击节点标记为完成，可选择星级
6. **删除节点**：进入删除模式，点击"🗑️"按钮
7. **自动排列**：删除节点后自动美观重排
8. **导入/导出**：在玩家面板中选择导入或导出技能树JSON

### 太阳系探索
1. **观察运动**：星体按真实轨道和速度运动
2. **调速**：拖动速度滑块(1-200，显示为0.1-20天/秒)
3. **缩放**：鼠标滚轮放大/缩小(0.3x-5x)
4. **拖动**：鼠标左键拖动移动视图
5. **查看信息**：单击行星查看参数
6. **地球详情**：双击地球查看大陆、海洋、云层细节
7. **重置**：点击"🔄 重置"回到当前真实时间

### 登山记录
1. 查看地图上的登山点
2. 添加新记录
3. 编辑/删除现有记录
4. 查看统计数据

### 玩家系统
1. 点击头像更换样式或图片
2. 点击昵称进行自定义修改
3. 勋章记录在玩家面板查看详情

## 📁 项目结构

```
LitterPutting/
├── CMakeLists.txt              # CMake构建配置
├── main.cpp                    # 应用程序入口
├── Skill.h                     # 技能数据结构（含starRating字段）
├── SkillModel.h/.cpp           # 技能树模型（含三星评价、云同步）
├── SolarSystemModel.h/.cpp     # 太阳系模型（天文计算）
├── MountainRecordModel.h/.cpp  # 登山记录模型
├── PlayerProfile.h             # 玩家数据结构
├── PlayerModel.h/.cpp          # 玩家模型
├── qml/
│   ├── AppMain.qml             # 主界面
│   ├── SkillTreeView.qml       # 技能树（含三星评价UI）
│   ├── SkillTreeView_Beautiful.qml  # 美化版技能树
│   ├── SolarSystemView.qml     # 太阳系（含行星纹理）
│   ├── EarthDetail3D.qml       # 3D地球详情视图
│   ├── MountainView.qml        # 登山记录
│   └── PlayerProfilePanel.qml  # 玩家面板
├── images/                     # 图片资源
│   ├── earth_day.jpg           # 地球纹理
│   ├── earth_clouds.png        # 云层纹理
│   ├── avatars/                # 玩家头像
│   └── README.md               # 资源下载指南
├── android/                    # Android配置
│   └── AndroidManifest.xml
├── qml.qrc                     # QML资源文件
├── docs/                       # 📚 文档目录
│   ├── 3D地球功能说明.md       # 3D地球完整文档
│   ├── 三星评价系统功能说明.md  # 三星评价系统
│   ├── 云同步功能说明.md       # Gitee云同步
│   ├── 玩家系统功能说明.md      # 玩家系统
│   ├── 图标设置指南.md         # 应用图标设置
│   ├── 构建和运行指南.md       # 编译运行指南
│   └── TODO.md                # 待实现功能清单
└── README.md                   # 本文件
```

## 🎨 设计亮点

### 1. 技能树自动排列算法
采用自底向上树形布局：
- 叶子节点优先定位
- 父节点居中对齐子节点
- 子树宽度递归计算
- 保证美观对称性

### 2. 真实天文数据
- J2000.0历元基准
- 真实轨道周期
- 精确位置计算
- 60FPS流畅动画

### 3. 无资源纯代码绘制
- Canvas绘制大陆轮廓
- Gradient渐变效果
- 无需额外资源包
- 性能优化良好

### 4. 儿童友好设计
- 大号按钮和文字
- Emoji图标
- 彩虹配色
- 流畅动画

## ✅ 开发进度

### 已完成（最新更新：2026-02-05）
- ✅ **🔦 天黑请闭眼模式更新**
  - **关卡重制**：全面扩展关卡面积与难度，修复迷宫死局
  - **移动手感优化**：单击极速响应 + 长按匀速移动（3格/s）
  - **视觉优化**：角色体积缩小适配通道，视野更开阔
  - **道具完善**：新增罗盘、地图等道具描述
  - **照明弹系统**：飞行轨迹照明 + 像素瞄准 + 爆炸范围照明
- ✅ 技能树基础功能
- ✅ 技能树自动排列算法
- ✅ 右键/长按重命名
- ✅ Enter键确认输入
- ✅ **⭐⭐⭐ 三星评价系统（最新）**
  - 三星可视化选择对话框
  - 重新挑战功能
  - 节点星级显示
  - 数据持久化和云同步
- ✅ **☁️ Gitee云同步功能**
  - 技能树数据云端存储
  - 跨设备自动同步
  - 冲突检测提示
- ✅ **🌍 3D地球详情视图**
  - Qt Quick 3D渲染
  - 实时晨昏线显示
  - 纹理贴图支持
  - 鼠标交互控制
- ✅ 太阳系真实天文模拟
- ✅ 行星纹理美化
- ✅ 月球公转动画
- ✅ 鼠标滚轮缩放
- ✅ 左键拖动视图
- ✅ 速度滑块优化
- ✅ 玩家系统（40+头像/昵称/积分）
- ✅ 界面美化（渐变/云朵/Emoji）
- ✅ 登山记录管理
- ✅ 数据持久化（QSettings）

### 待完善（详见 [📝 TODO.md](docs/TODO.md)）
- 🔄 超炫酷完成特效（点赞/烟花动画）
- 🔄 学科技能树（语文/数学/英语）
- 🔄 体育技能树完整实现
- 🔄 成就系统扩展
- 🔄 等级和金币商城
- 🔄 家长控制模式
- 🔄 社交分享功能
- 🔄 多语言支持

## 🤝 贡献指南

欢迎提交Issue和Pull Request！

贡献前请确保：
1. 代码符合Qt/C++最佳实践
2. UI设计适合6岁儿童
3. 功能具有教育意义
4. 提供必要的测试

## 📄 许可证

MIT License - 详见LICENSE文件

## 📚 详细文档

### 功能说明文档
- [🌍 3D地球功能说明](docs/3D地球功能说明.md) - 完整的3D地球详情视图文档
  - 真实3D渲染技术
  - 实时晨昏线显示原理
  - 纹理贴图使用指南
  - 交互操作说明

- [⭐ 三星评价系统功能说明](docs/三星评价系统功能说明.md) - 最新的三星评价功能
  - 三星可视化选择
  - 重新挑战机制
  - 星级显示和动画
  - 数据持久化

- [☁️ 云同步功能说明](docs/云同步功能使用指南.md) - Gitee云同步完整指南
  - Gitee仓库配置
  - 自动同步机制
  - 冲突处理策略
  - 故障排查

- [👤 玩家系统功能说明](docs/玩家系统和美化效果使用指南.md) - 玩家系统使用指南
  - 头像更换方法
  - 积分系统说明
  - 界面美化效果
  - 数据保存位置

### 配置和构建文档
- [🔨 构建和运行指南](docs/构建和运行指南.md) - 完整的编译和运行说明
  - Qt Creator构建步骤
  - 命令行构建方法
  - 常见问题解决
  - 纹理资源下载

- [🖼️ 图标设置指南](docs/图标设置指南.md) - Android和Windows图标配置
  - Android多尺寸图标
  - Windows ICO文件
  - 图标生成工具
  - 常见问题

### 开发规划
- [📝 TODO清单](docs/TODO.md) - 待实现功能和长期规划
  - 界面美化高级特效
  - 学科技能树扩展
  - 游戏化系统
  - 多平台支持

## 💬 反馈与支持

- 提交GitHub Issue
- 发送邮件至项目维护者
- 查看`docs/`目录获取详细文档
- 参考[TODO.md](docs/TODO.md)了解开发规划

---

**让孩子的成长过程更加有趣和可视化！** 🌟  
**用科技点亮未来，用游戏化激发学习热情！** 🚀