企业官网建设流程全解析

桌面宠物框架DyberPet上手指南：从跑通Demo到自制角色的完整路径

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

你是否曾经想过，让喜欢的动漫角色住在桌面上，陪你写代码、陪你吃外卖、在你摸鱼时提醒你该专注了？想动手实现，却发现"透明窗口"、"无边框置顶"、"帧动画"这些词每个都够研究一整天。DyberPet就是为此而生的开源项目：一套基于 PySide6 的桌面宠物框架，把动画、养成、任务、商店、迷你宠物统统封装好，你只需下载代码、跑起来、再往文件夹里放一套素材，一个"活"的桌宠就诞生了。这篇文章会带你走完从环境搭建、看懂核心机制，到做出自己专属角色的全过程，无论你是想自娱自乐还是二次开发，都能从中找到抓手。

先解决一个真实的痛点：桌宠为什么难做？

很多人第一次想做桌宠时，第一个念头是"不就是一个会动的 GIF 吗"。可真动手就会发现，事情远没那么简单。你可以回想一下桌面宠物的几个基本需求：

• 窗口必须是透明、无边框、始终置顶的，否则宠物会带着一个方框"盒子"出现；
• 动画要按帧播放，还要区分待机、行走、拖拽、下落等不同状态，状态之间要能平滑切换；
• 宠物要有"物理感"——被鼠标拎起来甩出去，松手后会下落，碰到屏幕边缘会反弹；
• 更进一步，还要有饱食度、好感度这类养成数值，数值变化要反过来影响宠物的行为。

每一个需求单独拎出来都有现成解法，但把它们缝合成一个完整应用，工作量立刻膨胀。DyberPet 的价值恰恰在于：它把上述这些"地基"全部打好，并且用JSON 配置把美术资源和程序逻辑彻底解耦。你不需要理解 Qt 的底层细节，只要按约定放图片、填参数，就能得到一只行为正常的桌宠。

十分钟跑通：环境准备与一键启动

DyberPet 要求 Python 3.9 及以上，核心依赖只有四个：PySide6、PySide6-Fluent-Widgets、apscheduler 和 pynput。我建议先创建一个干净的 conda 环境，避免污染其他项目：

conda create --name Dyber_pyside python=3.9.18 conda activate Dyber_pyside # 定时任务调度：饱食度下降、专注计时都靠它 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 # 用于禁止多开，防止存档写坏

依赖装好后，把仓库克隆到本地：

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

首次运行会看到一只小猫出现在屏幕角落，右键单击它就能呼出菜单。Windows 用户也可以直接下载打包好的 EXE，双击即用。这里有个小提醒：如果显示器缩放比例不是 100%，动画位置可能会偏移，可以进"系统设置"里手动调整每个角色的缩放参数，项目已经为多屏幕和缩放场景做了处理。

核心机制拆解：配置文件如何"喂"出一只活宠物

跑通之后，很多人会好奇：这只小猫的行为到底是谁在控制？答案在res/role/目录里。每个角色一个文件夹，里面只有两类东西——图片和 JSON。程序启动时，settings.py会扫描res/role/下所有子目录，把每个文件夹名当作一个可选角色；接着读取该角色的两个核心配置：

• pet_conf.json：定义角色的基本属性和"行为清单"
• act_conf.json：定义每个动作的图片序列、播放速度、移动方向

我们以自带的小猫 Kitty 为例，它的待机动画是这样声明的：

// res/role/Kitty/act_conf.json { "default": { "images": "stand", "act_num": 1 }, "left_walk": { "images": "leftwalk", // 使用 leftwalk_0.png ~ leftwalk_4.png "act_num": 5, // 共 5 帧 "need_move": true, // 播放时角色本身要移动 "direction": "left", // 向左走 "frame_refresh": 0.2 // 每 0.2 秒切一帧 } }

程序读取后，会把action/目录下的stand_0.png、stand_1.png… 依次加载成 QPixmap，按frame_refresh指定的间隔循环播放。图片帧的编号从 0 开始任意连续即可，程序会自动扫描，不强制要求统一命名长度。换句话说，做动画素材的本质就是：按动作名放一组序号连续的 PNG。

而 pet_conf.json 里真正有意思的是random_act字段，它把单一动作组合成"动画"，并配置了触发概率与状态门槛：

{ "random_act": [ {"name": "左右行走", "act_list": ["left_walk", "right_walk", "default"], "act_prob": 0.1, "act_type": [3, 1]}, {"name": "睡觉", "act_list": ["fall_asleep", "sleep"], "act_prob": 0.05, "act_type": [0, 0]} ] }

act_type的第一个数字代表饱食度等级（0 是饿昏、3 是活力满满），第二个数字是解锁所需的好感度等级。也就是说，当角色吃饱喝足时更容易活蹦乱跳，饿到不行时大概率只会趴着睡觉——养成数值和动画行为就这样被一条 JSON 串起来了。

信号与槽：模块之间如何"说话"

桌宠不是孤立的小动画。喂食要涨饱食度、涨了好感度要弹出通知、通知要写进日志、数值变了背包和商店界面要刷新……这些跨模块的联动，在run_DyberPet.py里集中完成。启动入口会创建五个核心对象：桌宠本体PetWidget、通知系统DPNote、附件系统DPAccessory、系统面板和仪表盘（Dashboard），然后用 Qt 的信号槽机制把它们的接口两两接起来。

# run_DyberPet.py 中的部分接线代码 self.p.setup_notification.connect(self.note.setup_notification) # 桌宠→通知 self.board.backpackInterface.use_item_inven.connect(self.p.use_item) # 背包→桌宠 self.p.addItem_toInven.connect(self.board.backpackInterface.add_items) # 桌宠→背包 self.p.fvlvl_changed_main_inve.connect(self.board.shopInterface.fvchange) # 好感度→商店

你可以把信号槽想象成一条条"消息管道"：某处状态一变，就向管道里喊一声，所有感兴趣的模块自动响应。这种设计的好处是模块之间彼此不需要知道对方存在，新增一个界面组件时，只要补几条 connect，完全不用改动业务逻辑。想要理解全貌的同学，直接通读这个文件里的__connectSignalToSlot()，等于看了一遍系统架构图。

从吃到玩：物品、Buff 与迷你宠物

数值系统是桌宠的"生命线"。饱食度（HP）每两分钟下降一点，好感度（FV）则通过互动累积，等级上限高达 200 级，从星星、月亮一路升到皇冠。为了让养成更有策略性，物品系统引入了Buff 机制（见DyberPet/Dashboard/buffModule.py），物品配置里加一段buff字段，就能定义持续生效的效果：

// res/items/Default/items_config.json 中的薯条 { "effect_HP": 8, "effect_FV": 2, "drop_rate": 0.5, "buff": { "effect": "coin", // 效果类型：掉金币 "interval": 30, // 每 30 秒触发一次 "value": 5, // 每次 5 金币 "expiration": 120, // 持续 2 分钟 "description": "使用后每30秒获得5金币，持续2分钟" } }

Buff 分为两类：一类是定时结算型（每隔 N 秒增减 HP/FV/金币），一类是状态变更型（比如"5 分钟内饱食度不再下降"）。系统会用 QThread 在后台跑一个循环，每秒刷新所有生效中的 Buff，到期后自动移除。这种设计让"道具"不再是一次性数值，而变成了有时间维度的策略选择。

迷你宠物是另一个亮点。你可以把res/pet/下的角色（比如派蒙）召唤出来，它会自动排队跟随主宠移动，被拖走也会自己跑回来。物品、宠物、动作全部遵循同一套"文件夹 + JSON"约定，这也是整个框架扩展性最好的地方。

三招让桌宠变成生产力工具

桌宠不只是卖萌。项目内置的任务系统可以把"宠物"变成"监督你的伙伴"：

1. 番茄钟：开始一个 25 分钟的番茄钟，宠物会切换到focus专注动画，倒计时结束自动结算奖励金币；
2. 自定义专注时长：在任务面板设置任意时长，结束后按已专注时间结算，中途取消也会按比例给奖励，不留挫败感；
3. 待办与提醒：备忘录支持到时提醒和间隔提醒，宠物会在你桌面弹出气泡通知——比系统弹窗可爱得多，也更容易被注意到。

更有趣的是对话气泡系统：摸摸头、喂食、饿肚子、频繁点击（1 秒内点 7 次）都会触发对应的气泡和语音，角色的性格感一下就出来了。这些气泡文案和图标都支持按角色独立配置，是低成本做出"人格化"效果的好途径。

进阶玩法：给角色加一套自定义动作

理解了配置体系后，扩展角色就变成了一件有章可循的事。以"给现有角色新增一个动作"为例，完整步骤是：

1. 准备帧图：在res/role/[角色名]/action/下放入myact_0.png、myact_1.png…（前缀即动作名）；
2. 声明动作：在act_conf.json中新增"myact": {"images": "myact", "act_num": 3, "frame_refresh": 0.1}；
3. 挂进行为列表：在pet_conf.json的random_act中加入包含"myact"的组合，并设定act_prob与act_type；
4. 导入验证：打开"系统"面板的角色管理，使用模组自动添加功能，程序会检查文件夹结构并给出错误提示，比手动排查高效得多。

如果只想调试不想动文件，Dashboard 里的"动画面板"还支持运行时添加、删除动作并立即播放预览。素材开发的具体规范（文件清单、每个字段的含义、可选的note/个性化通知、info/作者信息）都在docs/art_dev.md里有完整说明，官方社区也在持续收集第三方角色和物品模组，可以参考docs/collection.md里的合集。

常见问题与避坑建议

Q：动画位置对不上，或者角色"掉"到屏幕外？A：多半是显示器缩放比例导致。先确认系统缩放是否为 100%，再到设置里调整该角色的scale参数；多屏幕用户建议把主屏设为第一块屏幕，程序会按主屏坐标初始化。

Q：为什么我加了图片但角色报错？A：检查三点：文件是否用了英文命名（繁体中文在某些解压环境下会乱码导致崩溃）；act_conf.json里声明的images前缀是否和文件名一致；图片是否都是同尺寸的 PNG。素材开发文档里列了程序会自动校验的项目，先在系统面板里跑一次自动导入。

Q：鼠标拖拽手感怪，宠物飞太快？A：pet_conf.json里的interact_speed和全局的fixdragspeedx/fixdragspeedy分别控制交互响应和拖拽速度，先小幅调后两项试试。

Q：任务系统的"专注"功能不触发？A：专注动画是可选的，如果角色没有定义focus动作，程序会自动回退到默认动画，这不影响计时与结算。

总结：下一步可以怎么玩

DyberPet 把"桌面宠物"这个看似小而美的需求，做成了一套相当完整的工程：JSON 驱动的配置体系让美术与代码彻底解耦，信号槽架构保证了模块间的高内聚低耦合，而 Buff、任务、气泡、迷你宠物等子系统则为二次创作留足了空间。对于想学 PySide6 桌面开发的初学者，它是绝佳的"解剖样本"；对于想自娱自乐的玩家，它是一台"角色创造机"。目前项目正在开发大模型接入能力，未来你甚至可以和桌宠自由对话，让 TA 从"会卖萌"进化成"会帮你管理待办的生活助手"。

如果你也有一只一直想养在桌面的角色，不妨从克隆仓库、跑起 Demo 开始，然后照着素材开发文档，给它配一套专属动作。动手的那一刻，你会发现：桌宠并不难，难的是有人替你踩完了那些坑。

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