如何用 DyberPet 打造你的第一个桌面宠物：PySide6 桌宠框架完整上手指南

【免费下载链接】DyberPetDesktop Cyber Pet Framework based on PySide6项目地址: https://gitcode.com/GitHub_Trending/dy/DyberPet

很多人的电脑桌面都缺一个"活物"。养电子宠物的念头人人都有，但现实往往是：网上找到的桌宠要么是个只会左右晃的 GIF 播放器，要么代码耦合成一团，想换个形象、加个功能就得动刀动斧。DyberPet 正是为解决这个痛点而生的开源项目——一个基于 PySide6 的桌面宠物框架，官方代号"呆啵宠物"。它把动画播放、养成数值、任务系统、商店背包全部拆成了可配置的模块，你既能开箱即用地养一只会饿、会困、会回应你的角色，也能只用 JSON 配置文件就造出一整套全新的宠物模组。

它能做什么：30 秒建立全景认知

在动手之前，先用一张官方主界面截图建立直观印象。左侧是角色管理面板，列出了系统内置的多个角色，每个角色都可以一键"启动"；右侧是角色状态面板，饱食度、活力、好感度、陪伴天数一目了然，底部还有实时滚动的状态日志，记录每一次投喂和掉落。

把它拆开来看，这套桌宠框架的核心能力其实就四件事：

• 能动的角色：角色由多帧 PNG 图片构成，支持站立、行走、睡觉、生气等随机动作，点击会触发拍拍动画，拖拽会模拟重力下落。
• 能养的系统：饱食度随时间衰减、好感度按互动累积（上限 200 级）、物品使用带来临时 Buff，形成完整的养成闭环。
• 能玩的功能：番茄钟、专注计时、待办提醒、商店买卖、背包整理，桌宠不只是摆设，还能反过来帮你管理时间。
• 能换的内容：角色、物品、迷你宠物、音效、对话气泡全部以模组形式存在，放进指定目录即可被识别加载。

拆解核心：JSON 配置如何驱动一只会动的宠物

DyberPet 最值得深挖的设计，是把"程序逻辑"和"角色行为"彻底分离。程序负责调度，而"角色长什么样、会做什么动作、掉落什么物品"全部由配置文件说了算。

以自带角色 Kitty 为例，它的所有行为都收在两个文件里。首先是桌宠参数文件res/role/Kitty/pet_conf.json，定义了角色的尺寸、缩放比例，以及各类交互动作的名称映射：

{ "width": 98, "height": 98, "scale": 1.0, "default": "default", "drag": "drag", "fall": "fall", "random_act": [ {"name": "站立", "act_list": ["default"], "act_prob": 1.0}, {"name": "左右行走", "act_list": ["left_walk", "right_walk"], "act_prob": 0.1} ] }

其次是动作参数文件res/role/Kitty/act_conf.json，它负责把动作名翻译成具体的动画播放规则：

{ "sleep": { "images": "sleep", "act_num": 5, "frame_refresh": 0.5 }, "left_walk": { "images": "leftwalk", "act_num": 5, "need_move": true, "direction": "left", "frame_refresh": 0.2 } }

这里的关键理解在于：act_conf.json里的每个动作，都会去角色目录下的action/文件夹中找对应前缀的序列帧图片。比如sleep动作会按 0.5 秒的间隔依次播放sleep_0.png到sleep_4.png，拼出睡觉动画；而带need_move标记的left_walk，则在切帧的同时向左平移，形成真实的行走效果。也就是说，你准备一叠按序号命名的 PNG，再在 JSON 里写几句参数，一个全新的动作就诞生了。

物品系统也遵循同样的思路。打开res/items/Default/items_config.json，你会发现每个物品就是一段配置块：

{ "汉堡": { "image": "15_burger.png", "effect_HP": 10, "effect_FV": 3, "drop_rate": 0.5, "buff": { "effect": "HP_stop", "expiration": 300, "description": "使用后5分钟内饱食度不会下降" } } }

这段配置同时承载了三层信息：数值效果（回饱食度、加好感度）、掉落概率、以及持续 5 分钟的 Buff 状态。程序在后台通过一套基于 Qt 信号槽的机制，把"物品被使用"这一事件广播给状态面板、动画模块和通知系统——你点一下汉堡，数值变了、宠物做出进食动作、头顶弹出感谢气泡，整条链路不用写任何新代码。

三步完成环境配置并启动你的第一只宠物

想立刻跑起来，其实比想象中简单。官方目前主要支持 Windows 与 macOS 的源码运行方式，推荐用 conda 建一个干净环境：

第一步：创建并激活虚拟环境

conda create --name Dyber_pyside python=3.9.18 conda activate Dyber_pyside

第二步：安装核心依赖

Windows 与 macOS 的唯一区别是 pynput 的版本，其余依赖一致：

conda install -c conda-forge apscheduler conda install -c conda-forge pynput pip install PySide6-Fluent-Widgets==1.5.4 pip install pyside6==6.5.2 pip install tendo

其中apscheduler负责饱食度衰减、提醒等定时任务，pynput用于捕捉全局鼠标事件，PySide6-Fluent-Widgets则提供了 Windows 11 风格的现代化控件库。

第三步：克隆仓库并启动

git clone https://gitcode.com/GitHub_Trending/dy/DyberPet cd DyberPet python run_DyberPet.py

启动后角色会直接出现在桌面右下角。右键点击宠物即可呼出菜单，从这里可以进入角色面板、切换动作、查看背包，或召唤迷你宠物；Windows 用户也可以直接下载打包好的 EXE 体验，免去环境配置。

进阶玩法：从"用别人的宠物"到"造自己的宠物"

当你对默认角色玩腻了，才算真正进入 DyberPet 的核心价值区。项目把二次开发的入口整理得非常清晰，官方素材开发文档位于docs/art_dev.md，里面完整覆盖了四类开发场景：

• 角色开发：新建一个文件夹放进res/role/，准备pet_conf.json、act_conf.json和action/序列帧图片即可。文档特别提示，文件名务必使用英文，部分繁体中文环境解压素材会出现乱码导致崩溃。
• 物品开发：在res/items/下定义items_config.json，可配置消耗品与收藏品两类，支持好感度等级解锁（fv_lock）和附带 Buff 效果。
• 对话系统：通过note/目录下的bubble_conf.json定制对话气泡的图标、音频与文案，甚至可以用USERTAG、ITEMNAME这类占位符实现"宠物提到你的昵称"的个性化效果。
• 迷你宠物：复用主角色的动画框架，可设置跟随主宠排队、自由活动、大小缩放等属性。

如果你想做更贴近代码层面的修改，入口同样清晰：DyberPet/DyberPet.py是主控模块，负责窗口与交互调度；DyberPet/modules.py拆出了动画模块、交互模块和任务调度模块；DyberPet/Dashboard/下则按功能分好了statusUI.py（状态）、taskUI.py（任务）、shopUI.py（商店）等面板文件，改某个功能时直接定位到对应文件即可。

小结：下一步做什么

DyberPet 的价值不在于它替你养好了宠物，而在于它把"桌宠"这件事拆成了一个足够开放、足够规范的可扩展框架——动画由帧图驱动，行为由配置驱动，功能由模块驱动。对普通用户，它是一套完整可玩的桌宠应用；对想练手 Qt 开发的新手，它又是一份结构清晰、注释到位的 PySide6 实战教材。

接下来你可以按这个顺序继续探索：先跑起来感受交互，再打开docs/art_dev.md尝试给现有角色加一个新动作，最后试着做一套属于自己的角色模组放进res/role/。当你在右键菜单里看到自己定义的动画被正常播放时，那种"它活了"的感觉，就是桌宠开发最迷人的回报。

【免费下载链接】DyberPetDesktop Cyber Pet Framework based on PySide6项目地址: https://gitcode.com/GitHub_Trending/dy/DyberPet