# HanakamiPet

**Repository Path**: hanakami/hanakami-pet

## Basic Information

- **Project Name**: HanakamiPet
- **Description**: 使用Qt做的桌面宠物，主要是任务提醒，后续优化功能
- **Primary Language**: Unknown
- **License**: LGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-11
- **Last Updated**: 2026-05-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HanakamiPet

![version](https://img.shields.io/badge/version-2.0.2-f472b6)
![Qt](https://img.shields.io/badge/Qt-6.11-41cd52)
![platform](https://img.shields.io/badge/platform-Windows%20x64-60a5fa)
![license](https://img.shields.io/badge/license-LGPL--3.0-94a3b8)

HanakamiPet 是一个基于 Qt 6 和 Live2D Cubism Native SDK 的 Windows 桌面宠物。她会待在桌面上陪伴你、提醒任务、展示 Live2D 表情动作，也能通过右键菜单管理待办和检查更新。

<p align="center">
  <img src="assets/pet_main_transparent.png" width="260" alt="HanakamiPet 桌宠预览">
</p>

## 特性

| 功能 | 说明 |
| --- | --- |
| Live2D 桌宠 | 集成 Live2D 模型渲染，支持表情和动作触发 |
| 任务管理 | 添加任务、查看待完成/已完成/全部任务 |
| 主动提醒 | 桌宠会不定期关心你，也会提醒未完成任务 |
| 严重提醒 | 任务到期后会显示更醒目的红色提醒 |
| 设置面板 | 可配置随机提醒、气泡停留时间、自动巡逻等偏好 |
| 自动更新 | 从 Gitee 读取 `update.json`，发现新版本后弹出更新提示窗 |
| 透明点击 | 人物四周透明区域尽量不抢占鼠标事件 |
| 屏幕边界保护 | 拖动和自动移动时尽量保持人物可见范围不越界 |

## 运行方式

普通用户推荐下载 Release 包：

1. 打开 [Gitee Releases](https://gitee.com/hanakami/hanakami-pet/releases) 页面。
2. 下载 `HanakamiPet-v版本号-windows-x64.zip`。
3. 解压后运行 `HanakamiPet.exe`。

不要只复制单个 `exe` 给别人使用。Qt 运行库、Live2D 模型、Cubism Core DLL 等文件都需要和 exe 放在同一个发布目录中。

## 开发环境

推荐环境：

| 工具 | 版本 |
| --- | --- |
| Windows | Windows 10/11 x64 |
| Qt | 6.11.0 MSVC 2022 x64 |
| MSVC | Visual Studio 2022 x64 |
| CMake | 3.21+ |
| Live2D SDK | Cubism SDK for Native 5-r.5 |

工程默认从 `third_party/CubismSdkForNative-5-r.5` 引用 Live2D SDK，并从 `live2d/models/xiaoyue` 复制模型资源到构建产物目录。

## 构建

在 Qt Creator 中打开 `CMakeLists.txt`，选择 `Desktop Qt 6.11.0 MSVC2022 64bit` Kit，使用 Release 配置构建即可。

也可以在已生成 Makefile 的 Release 构建目录中执行：

```powershell
$env:QTFRAMEWORK_BYPASS_LICENSE_CHECK='1'
cmd.exe /c 'call "C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\VC\Auxiliary\Build\vcvars64.bat" && nmake -f Makefile'
```

构建完成后，`windeployqt` 会自动部署 Qt 依赖，并复制 Live2D 模型和运行时资源。

## 发布流程

发布给朋友使用时，推荐流程如下：

1. 修改 `CMakeLists.txt` 中的项目版本号。
2. Release 构建项目。
3. 整理完整发布目录，不要遗漏 DLL、`qml`、`plugins`、`live2d`、`FrameworkShaders` 和 `update.json`。
4. 压缩为 `HanakamiPet-vX.Y.Z-windows-x64.zip`。
5. 上传到 Gitee Release。
6. 更新仓库根目录的 `update.json`：

```json
{
  "version": "2.0.2",
  "notes": "本次更新说明",
  "url": "https://gitee.com/hanakami/hanakami-pet/releases/download/v2.0.2/HanakamiPet-v2.0.2-windows-x64.zip",
  "force": false
}
```

应用启动后会自动检查更新；用户也可以通过右键菜单手动检查。

## 目录结构

```text
qt/
├─ assets/                  # 图标和静态素材
├─ live2d/models/xiaoyue/   # 当前桌宠 Live2D 模型
├─ qml/                     # 桌宠窗口、菜单、任务面板、设置和提醒 UI
├─ resources/               # Windows 资源文件
├─ src/                     # C++ 服务、模型、Live2D 渲染和窗口辅助逻辑
├─ third_party/             # Live2D Cubism SDK for Native
├─ CMakeLists.txt
└─ update.json
```

## 注意事项

- 如果朋友电脑提示缺少 `Qt6Gui.dll`、`ucrtbased.dll` 等文件，通常是发错了 Debug 版或只发了单个 exe。请使用 Release 版完整发布目录。
- `third_party` 目录包含 Live2D SDK，请确认分发方式符合 Live2D 官方许可要求。
- `.qtcreator`、`build`、`dist`、`releases`、`tmp` 等本地构建和临时目录不建议提交到 Git。

## License

本项目代码使用 LGPL-3.0 License。Qt、Live2D Cubism SDK、模型素材等第三方内容遵循各自的许可协议。