qqpet README

The project's README from github.com/AnkioTomas/qqpet. As one markdown file: README.md.

QQPet

QQ 宠物跨平台复刻(Windows / macOS / Linux / Android / HarmonyOS / iOS),基于 Arctic Penguin T800 逆向重建。Flash 内容由 Ruffle 播放。

版权声明:QQ 宠物的美术资源与 SWF 版权归腾讯所有;旅行照片素材版权归《旅行青蛙·中国之旅》所有。本项目仅供学习交流,请勿用于商业用途。

截图

桌面宠物与右键菜单
桌面宠物与右键菜单
商城与背包
商城与背包
宠物资料
宠物资料
图鉴与签到
图鉴与签到
今日任务
今日任务
全国旅游
全国旅游
系统设置
系统设置

功能

存档位于 userData/save.json,导入时旧存档备份为 save.json.bak。

桌面版支持将宠物拖到其他显示器(包括主屏左侧或上方、不同缩放比例的屏幕),重启后回到上次所在的显示器;该显示器断开时回到主屏幕。

iOS

最低目标为 iOS 14.0。安装需使用保留所需权限的越狱 App 安装器或 TrollStore,后者的系统兼容范围以其上游说明为准。全局 HUD 依赖系统私有接口和所需权限,普通开发者签名不能替代这些权限。打开管理 App,点击「开始桌宠」,返回主屏幕后桌宠继续显示在其他应用上方。打开管理界面会暂时隐藏桌宠;「宠物菜单」「宠物状态」可显示相应界面,「返回管理」用于回到管理操作。

复用完整养成、界面和 SWF 内容,增加原生触摸分区、游戏展示和系统文件选择器导入导出。HUD 输入框通过前台管理器的原生编辑框提交文字。剪贴板文本由用户主动发送;后台剪贴板监听及前台应用观察暂不提供,因而也不提供其他 App 全屏时自动隐藏,设置会说明平台能力限制。此版本不安装 daemon,也不提供开机自启;完整重启后需手动开始。

本地使用 Node 22.12 或以上版本、公开 iPhoneOS SDK 和本地 ldid(也支持 ad-hoc codesign)。资源准备是独立步骤,普通构建使用本地文件:

ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm ci --ignore-scripts
npm run prepare:ios-assets
npm run ios

产物为 out/ios-native/QQPetIOS.ipa。安装器需保留 IPA 内的 entitlement。共用渲染代码以 Safari 14.0 能力为底线,构建会降级 Ruffle 回退 WASM 的符号扩展指令,并验证结果只依赖基础特性;Electron 外壳保留原有最低 macOS 版本要求。构建选项、存档路径、后台生命周期和平台限制见 iOS 使用说明。

Android

宠物以悬浮窗形式显示在桌面和其他应用上方,功能与桌面版一致,另有以下适配:

HarmonyOS

纯血鸿蒙(HarmonyOS NEXT / 5 及以上)不能装 Android APK。宠物同样以悬浮窗显示,JS 桥和 Android 是同一份 QQPetNative 契约,原生壳在 harmony/,渲染层不改。

本地打包:npm run harmony,需要本机 DevEco Studio(harmony/hvigorw 默认使用 /Applications/DevEco-Studio.app,可用 DEVECO_SDK_HOME / NODE_HOME / JAVA_HOME 覆盖)。产物在 harmony/entry/build/default/outputs/default/。

GitHub Actions 打 v* 标签时产出未签名 HAP 并放进 Release。和桌面包一样没有商店签名;用 hdc 装到模拟器或已开启调试的真机。上架或普通真机日常安装要在 DevEco 里配签名,目前仓库没有这份材料。

下载安装

从 Releases 下载对应平台的安装包:

平台 文件
Windows QQPet.Setup.<版本>.exe
macOS(Apple 芯片) QQPet-<版本>-arm64.dmg
macOS(Intel) QQPet-<版本>.dmg
Linux QQPet-<版本>.AppImage 或 qqpet_<版本>_amd64.deb
Android(11 及以上) QQPet-<版本>.apk
HarmonyOS(5 及以上) QQPet-<版本>.hap
iOS(需 TrollStore 或越狱) QQPet-<版本>-ios.ipa

桌面安装包没有代码签名,系统会拦截首次运行。各平台安装方式:

征集素材

社区里能找到的 QQ 宠物原版资料很少,大量游戏画面和素材已经缺失,复刻时只能靠猜。如果你手上有下面这些东西,欢迎提供:

提交方式:在 Issues 发帖说明你有什么,文件较大可附网盘链接。提交的素材版权仍归腾讯所有,只用于本项目的学习复刻。

开发

git lfs install && git lfs pull   # resources/pet 由 Git LFS 管理
npm ci
npm run dev

构建

npm run dist      # 类型检查 + 构建 + 打包当前平台安装包到 dist/
npm run android   # Android debug APK
npm run harmony   # HarmonyOS debug HAP(需要本机 DevEco Studio)
npm run ios       # iOS IPA(资源、SDK 和签名工具见 iOS 说明)

推送 v* 标签时由 GitHub Actions 打出三平台安装包、Android APK、Harmony HAP 和 iOS IPA 并发布 Release。iOS 及共用代码的 pull request 还会生成可下载的 IPA。iOS CI 在 Ubuntu 上使用固定版本的 LLVM、SDK 和 ldid,并打包完整资源。

Android 版本地调试用 npm run android(debug 包,输出到 android/app/build/outputs/apk/debug/),需要 Android SDK 和 JDK 17(Gradle 8 不支持更新的 JDK,可用 JAVA_HOME 指定)。CI 打的 release 包需要在仓库 Secrets 中配置签名密钥:

Secret 内容
ANDROID_KEYSTORE_BASE64 keystore 文件的 base64(base64 -i release.jks)
ANDROID_KEYSTORE_PASSWORD keystore 密码
ANDROID_KEY_ALIAS 密钥别名
ANDROID_KEY_PASSWORD 密钥密码

每次发布都必须用同一个 keystore,否则已安装的用户无法覆盖升级。

改过的 SWF

以下文件用 JPEXS FFDec 打过补丁,重新导入资源时不要覆盖:

文件 改动
resources/pet/mstx/qq_mstx.swf 隐藏需要联网的「兑换礼包」「魔法爱情石」按钮
resources/pet/qqfarm/Farm.swf 允许在 file:// 之外启动;「金币」改为「元宝」;商店可买的种子排前、其余置灰,购买后弹出提示;商店、仓库的弹出动画改为缩放比例,不再被异步加载的图片压窄;不绘制房屋、篱笆、狗窝
resources/pet/qqfarm/props.swf 素材中的「金币」文字改为「元宝」
resources/pet/smallGame/{100ceng,ball,paopao2}/ 下读屏幕尺寸的 26 个 SWF Capabilities.screenResolutionX/Y 改为 ExternalInterface.call("API.GetScreenWidth/Height")(Ruffle 返回的是播放器自身尺寸)

目录

路径 说明
src/main 主进程:窗口、托盘、app:// 协议、存档、AI 与天气请求
src/preload window.qqpet 接口
src/renderer 界面(原生 TypeScript),pet/ 为养成逻辑,ui/ 为各窗口,swf/ 为 Ruffle 封装
src/shared 主进程与渲染层共享的 IPC 与存档类型
src/android Android 版的 window.qqpet 实现,经 WebView 接口调用原生层
android/ Android 原生工程:悬浮窗服务、游戏页、文件选择、文字分享入口、开机自启
src/harmony HarmonyOS 版的 window.qqpet 实现,经 ArkWeb 接口调用原生层
harmony/ HarmonyOS 原生工程:浮动窗、游戏页、存档选择、分享入口
resources/pet 原版资源,npm run import-assets -- <app.asar> 可重新导入
tools/ 反混淆脚本、原版 CSS 移植脚本、CDP 调试脚本

许可证

本项目代码以 GPL-3.0 发布。该许可证不覆盖 resources/pet 下的原版美术资源、SWF 与旅行照片,它们的版权归各自所有者,见文首版权声明。

友情链接

本项目认可 LINUX DO 社区。

qqpet (AnkioTomas/qqpet)

Searching Database…

664 ·GitHub
What is this?QQPet is a cross-platform remake of the classic QQ desktop pet (QQ宠物), rebuilt by reverse-engineering the original Arctic Penguin T800 client; it plays back the original Flash (SWF) assets through the Ruffle emulator and lets a virtual pet live on your Windows, macOS, Linux, Android, HarmonyOS, or iOS device with feeding, games, school/work, and travel features.
Is this an Electron app or something else?The desktop versions (Windows/macOS/Linux) are built with Electron and TypeScript; Android and HarmonyOS have native wrapper apps that reuse the same rendering/SWF layer through WebView or ArkWeb bridges, and the iOS build is a native shell too since it can't run Electron.
Do I need a jailbroken device to run it on iOS?Yes — the iOS build (minimum iOS 14.0) must be installed through TrollStore or a jailbreak App installer that preserves its entitlements, since a normal developer signature can't grant the global HUD permissions the overlay pet needs.
Are the installers signed, or will my OS complain?None of the desktop installers are code-signed, so the OS blocks the first run — Windows SmartScreen needs 'Run anyway', macOS needs a Gatekeeper workaround or an xattr command, and HarmonyOS's unsigned HAP must be sideloaded with hdc instead of the app store.
How does the pet behave on Android and HarmonyOS phones?On Android and HarmonyOS, QQPet runs as a floating overlay window on top of other apps; the first launch needs 'display over other apps' and notification permissions, and since the OS blocks background clipboard reads, you share selected text to the pet via the share/selection menu instead.
Does chatting with the pet require an OpenAI API key specifically?No, the AI chat feature is optional and works with any OpenAI-compatible API endpoint, used for pet small talk, rewriting lines, and commenting on or translating clipboard text.
What's the deal with the patched SWF files?Several original Flash files were patched with JPEXS FFDec — for example QQFarm's in-game currency was renamed from 'gold coins' to 'ingots' and mini-game screen-size checks were rewired to work under Ruffle — and these patches must not be overwritten when re-importing original assets.
Can I bring over my old save file?Yes, QQPet can import saves compatible with the original config.json format, even from the first-run egg-selection screen, and automatically backs up the previous save as save.json.bak.
Creator
AnkioTomas
Size
5.9 MB
Stars
664
Age
10d
Commits · 90 Days