Pettime · Qt 桌宠

基于 haichaojiang01-stack/pettime 重构的 C++17 / Qt 6 蟑螂桌宠，保留原项目素材与行为设计。支持桌面爬行、食物与成长、摸摸互动、成年繁殖，以及局域网派遣和召回。

当前版本 0.3.6，网络协议 5，派遣能力 dispatch-v2。运行基线为 Ubuntu 24.04 / X11；Windows 0.2.0 曾通过编译和分发包运行库加载检查，当前版本仍待 Windows 编译与实机验收。

文档导航

文档	内容
更新日志	各版本功能变更与兼容性变化
验证记录	实际测试结果、环境和未验证范围
互动与繁殖设计	互动参数、计时、所有权与结算规则
网络设计	设备发现、连接、源码指纹与资源边界
派遣设计	离入场、隐藏确认、断线恢复与快照协议
第三方说明	上游素材与 Qt 等依赖的许可说明

本页说明当前版本的构建和使用方式；旧版规则见更新日志。

构建与运行

最低要求：C++17、CMake 3.21、Qt 6.4。应用使用 Qt Core、Gui、Widgets、Network，测试另需 Qt Test；无需 QML、独立游戏引擎或直接的 X11 开发库。运行所需 PNG 均嵌入程序，无需从源码目录启动。

Ubuntu 24.04

sudo apt install build-essential cmake qt6-base-dev
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
./build/pettime

默认构建测试；只构建应用时，在配置命令增加 -DBUILD_TESTING=OFF。安装到个人目录：

cmake --install build --prefix "$HOME/.local"

安装后仍需要系统 Qt 6 共享库及 X11 平台插件。存档默认写入可执行文件目录，目录必须可写；也可用 --data-dir /path/to/data 指定保存位置。

Windows 编译与分发

双击根目录的 build-windows.cmd，或在 PowerShell 中执行：

.\build-windows.cmd

脚本默认使用 C:\msys64\ucrt64 中的 GCC、CMake、Ninja、Qt 6、windeployqt6 和 objdump，以 Release、BUILD_TESTING=OFF 构建，再调用 package-windows.ps1 生成：

build-windows\Pettime-windows-x64.zip

分发 ZIP，完整解压后启动其中的 Pettime-windows-x64\pettime.exe。 接收方不需要安装 Qt、MSYS2 或修改 PATH。不要只复制构建目录中的裸 EXE，也不要在压缩包浏览器中直接启动。

分发包包含 Qt 运行库和插件、GCC 运行库、递归收集的第三方 DLL、动态加载的 OpenSSL DLL、许可文本及 SHA-256 清单；qt.conf 指定包内插件路径。打包使用全新临时目录，遇到部署失败或无法解析的非系统 DLL 时返回错误。成功后覆盖同名 ZIP；失败时旧 ZIP 可能仍在，应以脚本成功提示为准。

脚本不运行测试或启动程序，也不安装软件或修改系统环境变量。不带参数运行时结束后暂停；第一个参数可指定输出目录，此时不暂停。工具链不在默认位置时：

$env:PETTIME_UCRT64 = 'D:\msys64\ucrt64'
.\build-windows.cmd .\build-windows-custom

使用同一套 UCRT64 编译器和 Qt，不复用其他工具链的构建目录。默认 build-windows/ 已被 Git 忽略；自定义目录也不应提交 EXE、DLL、ZIP 或构建缓存。Windows 既有验证结果及工具链版本见 验证记录，不代表当前版本已通过实机验收。

桌面操作

• 启动后自动爬行。左键拖动主宠物，右键打开菜单；托盘提供相同控制入口，双击托盘可召回主实体。重复启动会恢复已有实例的正常显示，将主实体召回鼠标所在屏幕中央；无托盘时仍可用右键菜单和重复启动控制。
• 菜单可调整大小、活跃程度、数量上限、暂停状态，打开各管理面板，或触发飞扑、召回与退出。主实体处于幼体阶段时不能使用成体动作和大小菜单。
• 行走采用交替三足步态，动画按实际位移推进，待机时触角仍活动。群体幼体会分散游走、避让同伴并随机起飞；规模增大时降低群体更新频率。
• 鼠标靠近并移动会触发躲避。5 秒内连续追逐，从第三次躲避起有 12% 概率飞扑，之后每次增加 10 个百分点，最高 70%；5 秒无追逐后重新计数。
• 暂停、拖动和打开宠物右键菜单会冻结主宠物的动作时间与帧，群体独立活动，自然成长继续。GNOME 外部托盘菜单不冻结动作；摸摸计时不因菜单打开而暂停。
• 主宠物拖入另一块屏幕后在该屏幕活动。显示器移除或工作区变化时重新约束位置；入离场中的实体从当前位置重算剩余路径。
• 宠物窗口仅在实际绘制区域接收点击；飞扑裂纹和高亮装饰始终不接收鼠标输入。

隐藏蟑螂（置底）

“隐藏蟑螂（置底）”将本机所有宠物（含访客）、高亮与裂纹窗口置于普通窗口下方，并让宠物窗口输入穿透，避免工作时误操作；切换时取消正在进行的拖动。模拟、成长、互动计时及食物掉落继续，新建窗口继承该模式，管理、食物、互动和网络面板仍可操作。

取消托盘中的勾选，或在管理／食物／互动面板点击“恢复蟑螂显示”，即可恢复正常置顶；托盘召回和重复启动也会恢复。恢复不会重新显示已因派遣交接而隐藏的本机窗口，访客仍然输入穿透。置底设置随配置保存。

实体管理

“蟑螂列表…”显示编号、名称、归属、动作、所在设备、派遣状态与成长度。宠物右键进入会选中对应实体，托盘进入默认选中主实体。

功能	规则
主实体	编号固定为 1，名称取当前主机名；分裂、容量清理均不删除主实体
数量上限	包含主实体，默认 72，可设 1～72 并保存；降低上限立即移除最早生成的超额普通实体并取消待生成队列
重命名	普通实体最多 64 字符，清空恢复“蟑螂 #编号”；名称随进度保存，新生子体不继承名称
高亮定位	显示 3 秒黄色光圈和名称，不拦截鼠标；冻结或不可见的派出实体不可高亮
批量选择	“全选本机自有子体”排除主实体及已派出实体；“全选访客”只选外来实体。替换当前选择，无匹配时清空，不自动执行操作
清除	单选仍在本机的自有非主实体后立即删除，无确认框、踩扁动画或分裂；主实体、访客和派遣／返回入场中的实体不可清除

清除同时结束控制、高亮和未完成互动，未完成进食按规则退款；不修改上限、不复用编号、不新增分裂任务，已有待生成任务继续处理。蟑螂与网络设备列表刷新时保持选择及滚动位置，条目减少时按新范围调整；网络设备列表没有实体批量选择按钮。

手动控制非主实体

单选自己的非主实体，点击“开始控制”，使用 WASD 或方向键移动，支持斜向，松键停止；面板内方向键不会切换选中行。本地及正常派出的实体均可控制，派出实体仍由来源端计算，目标端只渲染。主实体、访客、摸摸中、交接、入离场或冻结的实体不能开始控制。

控制期间暂停自主行走，保留成长。幼体进食时暂时停止移动，结束后继续接受控制；高亮不影响移动。面板失焦或打开重命名对话框时清除按键，重新聚焦需重新按键。停止控制、切换选择、关闭面板、派遣／召回、摸摸或删除实体时结束控制。断线结束控制并冻结实体，重连后需重新点击“开始控制”。

食物与成长

“食物面板…”可选择自有幼体，包括主实体及正常派出的实体；列表的“食物…”打开同一面板并选中目标。成体不可使用面包屑，访客不可投喂。来源端扣库存并结算成长，接收端只显示。

项目	当前规则
面包屑库存	首次运行 3 粒，上限 30 粒，包含正在进食的预留
自然掉落	每隔随机 180～300 秒有效运行时间获得 1 粒，不依赖网络服务开关
成长加成	每粒随机增加 0.5～1.5 个百分点，以 0.1 为步长；不增加好感度
进食过程	开始预扣 1 粒，约 2.65 秒吃完后结算；进食时自然成长继续
自然成熟	每只幼体每代固定抽取 30～60 分钟，按有效运行时间成长，时长随进度保存
生长阶段	初始主实体为 100%；新生子体为 0%。不足 25% 为“幼体”，25%～不足 100% 为“成长中”，100% 为“成体”

满仓暂停掉落计时且不积压；预扣转为预留不会腾位，吃完实际消耗后重新抽取掉落间隔。离线、休眠及超过 1 秒的事件循环停顿不补发食物，也不补算成长。

进食、摸摸、正面飞扑、派遣申请及交接、入离场、冻结、踩扁或退场时不能开始进食。取消、删除或重启时未吃完则退还预扣食物且不加成长；已经吃完再删除不退款。断线冻结保留未完成进食与预留，恢复后继续。开始时是幼体且吃完，即使途中成熟也结算消耗；成长上限 100%，实际增加量可能小于抽中值。

体型随成长连续变化，成体手动调整大小不改变成长。子体成年后仍是普通实体。列表向下截取一位小数，避免提前显示 100%；踩扁或容量淘汰退场时不增长，派遣入离场按活动时间成长。

互动与繁殖

从托盘、宠物右键菜单或列表“互动…”打开互动面板，选择自有实体，查看好感度、成熟状态、冷却和操作结果。

操作	效果与限制
摸摸	幼体和成体均可；约 2 秒完成，随机增加 2～4 点好感度，独立 10% 概率获得 1 粒面包屑。全客户端从开始起共用 10 秒冷却，换目标不能绕过
生殖	仅本机自有成体；保留亲体，新增 1 只 0% 成长幼体。首次成年即可用，成功后亲体独立随机冷却 10～20 分钟；不增加好感度、不抽奖
双击分裂	仅本机自有成体；普通成体消失并产生 4 只幼体，主实体退回幼体并新增 3 只，含自身共 4 只。幼体双击不踩扁、不分裂

新建实体好感度为 40，范围 0～100；每只每隔随机 30～60 秒下降 1～2 点。已有存档的合法好感度（含 0）保留，缺少字段采用 40。主实体分裂保留身份、好感度和年龄，新生子体从 40 开始，代数为亲体代数加一。

满好感仍可摸摸抽奖，满库存不积压奖励。中断摸摸不发奖励，已开始的冷却保留；普通点击、拖动、召回及打开面板不算摸摸。进食、摸摸、正面飞扑、交接、过渡、冻结或退场期间不能启动冲突操作，鼠标拖动与摸摸／生殖也互斥。

生殖在满员或有待生成队列时禁用，不淘汰实体、不消耗冷却。分裂仍沿用旧普通实体淡出腾位的容量规则，低上限可能少于 4 只；上限为 1 时主实体只恢复自身。分裂无额外冷却，但幼体须重新成年才能再次分裂或生殖。

正常派出的自有实体可在来源端摸摸，接收端只显示动画和好感度；繁殖须先召回并完成入场，访客只读。暂停爬行、菜单打开及置底不停止好感度衰减和生殖冷却；冻结、离场、踩扁和退场时暂停，离线／休眠不补算。摸摸冷却独立于单个实体冻结，重启取消未完成动作但保留冷却。

完整状态限制、计时与一次性结算规则见 互动与繁殖设计。

局域网联机

从“网络面板…”手动开启网络服务；首次运行默认关闭，之后恢复保存的开关。仅打开面板不启用服务，关闭面板也不停止服务。

• 双方都需开启服务。UDP 21012 每 10 秒广播发现同一 IPv4 子网设备，TCP 21012 握手后保持双向长连接；防火墙和路由器客户端隔离可能阻止发现，程序不修改这些设置。
• 应用版本、协议版本、完整源码指纹必须全部一致才能互联和派遣。 不匹配设备仍可扫描到；刷新不会绕过校验。指纹由 CMake 自动生成，文档、测试、Windows 打包脚本和构建产物不参与计算；详细范围见 网络设计。指纹用于防止代码误配，不是身份认证。
• 面板显示设备名、IP、端口、数量／上限、版本、协议、指纹、连接状态与最后通讯时间，多网卡按设备 ID 去重。“立即刷新”查询并尝试重连，不拆掉健康连接；数量资料最多每秒推送一次。
• 基础连接每 10 秒心跳，静默失联约 30 秒断开；主动端按 1～30 秒退避重连，120 秒无有效通讯的设备移出列表。派遣另有约 3 秒异常检测与 30 秒恢复宽限期。
• 端口占用会回滚启动并显示错误。仅接受参与网卡直接连接子网内的 IPv4 来源，socket 使用直连；最多 64 个已连接对端。无公网发现、认证或加密，仅用于可信局域网。

派遣、召回与驱赶

在“蟑螂列表…”选择一只或多只普通实体，点击“派遣…”并选择目标；主实体不能派遣。来源端保留实体和全部模拟、成长、食物及互动结算，接收端只渲染。派出实体仍占来源端数量上限，访客不占接收端自有上限；访客与预留另限 144 只。

派遣从本机当前位置向最近边直线离场，用时 1～3 秒；整个窗口越过边缘并同步隐藏后，才在目标主屏幕相对边入场，向内行走约 1 秒。窗口按所在屏幕可用区域裁剪，避免从相邻显示器露出。

来源端可单只或全部召回，接收端可“驱赶回原设备”。在线返程先让访客离场，接收端完成末帧插值、同步隐藏宠物及高亮并确认后，来源端才从原本机离场边入场。入场中也可折返；尚未交接的申请可取消。

正常派出的实体支持来源端命名、高亮、控制、幼体进食与摸摸。申请、交接及入离场禁止启动冲突操作；开始离场结束控制，取消未完成进食并退款，取消未完成摸摸。接收端访客只读且鼠标穿透，未命名访客显示“来源主机名 #编号”，置底由接收端设置决定。

断线冻结相关实体的模拟、成长、过渡与访客画面，保留 30 秒宽限期；重连核对原阶段和新状态流后继续，不补算离线时间。冻结时只接受命名和召回意图，已开始的进食／摸摸保留。离线召回等待重连返程或宽限期结束后本机入场；离线驱赶立即隐藏访客并记录结束，迟到消息不能复活已结束或已删除的实体。

静默断流约 3 秒后才判定异常，从实际断流到宽限期结束通常约 33 秒。双方检测时刻可能不同，异常网络分区不能保证绝无短暂重叠。当前不实现断线临时接管或访客本地交互。

主动关闭服务会先停止接受新派遣、召回派出实体并清理访客，完成后释放连接；断线仍沿用宽限期。退出程序直接清理，不等待动画。重启不恢复旧派遣；接口暂时消失时服务等待恢复。协议细节见 派遣设计。

数据保存与迁移

默认数据目录为可执行文件所在目录，与终端当前目录无关；可用 --data-dir /path/to/data 覆盖。首次运行自动创建文件，每 5 秒自动保存，正常退出再保存一次；使用原子替换。保存失败会提示并保留内存进度，30 秒后重试，也可从菜单重试。存档不绑定设备，不做防篡改校验。

文件	内容
config.json	数量上限、暂停、活跃程度、网络开关和 bottomMode 置底设置；网络端口仍为 21012
progress.json	自有实体编号、下一编号、名称、成长、growthDuration、好感度、代数、年龄、大小与位置；每实体 affectionDecayRemaining、reproductionRemaining；顶层 interaction.cooldownRemaining；food 内的可用库存 count、掉落倒计时 dropRemaining 和预留实体编号 pending
network-device-id.dat	当前客户端持久化随机网络标识，每次开启服务另生成会话 ID
runtime.log / runtime.log.1	轮转运行日志

实体表决定数量，生长阶段由成长推导。主实体始终存在，名称取当前主机名；恢复位置限制在可用屏幕内。派出的自有实体保存有效原本机坐标，屏幕外过渡位置限制到本机安全区域，不保存远端坐标。食物消耗与成长、摸摸好感度与奖励、生殖亲体冷却与子体记录均随同一份进度原子保存。

迁移前退出程序，复制 config.json 和 progress.json 到另一份程序旁即可。多台机器同时使用时不要复制 network-device-id.dat，让目标自行生成独立 ID。重启将派出实体恢复本机，不恢复访客、连接、派遣、控制、过渡、进食、摸摸和待生成队列；未完成食物预留只退款一次，未完成摸摸不补奖。

旧存档保留已有成长百分比与合法好感度；缺少 growthDuration 的幼体抽取 1800～3600 秒时长，缺少食物记录采用 3 粒，缺少好感度采用 40。损坏 JSON 会提示并使用默认值，写入前保留 .invalid 备份；仅做格式与必要范围检查。

对应 JSON 不存在时自动读取旧设置，不删除旧文件。确认迁移成功后可自行清理旧路径：

• Linux：~/.local/share/Pettime/Pettime/，或 $XDG_DATA_HOME/Pettime/Pettime/。
• Windows Qt 版：%LOCALAPPDATA%\Pettime\Pettime\。
• Windows 早期 C# 版：%LOCALAPPDATA%\XiaoqiangPet\，导入 affinity.dat。

旧版只保存好感度、数量上限与设备标识，不能恢复未保存的实体进度；population-limit.dat 等仅用于首次迁移，新版不向旧目录写入，网络标识在新目录独立生成。单实例锁与本地通信按数据目录及会话隔离，传相同 --data-dir 重复启动会召回对应实例。

平台边界

Ubuntu X11 为已验证基线。原生 Wayland 后端会提示限制并退出；可在具备 XWayland 的环境尝试 QT_QPA_PLATFORM=xcb ./build/pettime，但不保证完整行为。置底依赖窗口管理器支持 _NET_WM_STATE_BELOW。

Windows 使用公共 Qt API 和现有无边框窗口，当前 0.3.6 的窗口层级、输入及联机仍待实机验收。其他 Linux 窗口管理器、真实混合 DPI 多屏和 macOS 尚未完成验收；具体版本的测试范围以 验证记录 为准。

测试与动作导出

ctest --test-dir build --output-on-failure
./build/pettime --export --output /tmp/pettime-frames
./build/pettime --smoke --output /tmp/pettime-smoke
./build/pettime --smoke --smoke-pets 72 --duration 6 --output /tmp/pettime-smoke-72

CTest 目标	主要覆盖
fingerprint_tests	源码指纹范围、换行／路径一致性和增量更新
pettime_tests	行为、成长、好感度、繁殖、容量、存档、单实例及崩溃恢复
network_tests	发现、握手、刷新、推送、心跳、重连、协议校验及面板开关
dispatch_tests	派遣交接、快照、断线恢复、所有权和列表操作
food_tests	掉落、库存与预留容量、退款幂等及奖励接口
food_application_tests	食物面板、完成／取消／删除／重启结算及共同保存
interaction_application_tests	互动面板、共享冷却、一次性奖励、生殖限制及保存恢复
window_mode_tests	置底、输入和焦点属性、窗口恢复、高亮与裂纹

--export 默认使用 offscreen，导出九组动作帧、序列图和背景对照图，不会召回已有桌宠。--smoke 默认运行 6 秒并演示一次飞扑，输出 smoke.json、live-buffer.png，失败返回非零；存档隔离在输出目录 run-data/。--smoke-pets 支持 1～72，--duration 支持 3～120 秒。报告的更新耗时不包括合成器完整显示耗时。

Linux 还提供显式运行的 X11 探针，需要 X11/XTEST/XShape 运行库及显示服务访问权限：

QT_QPA_PLATFORM=xcb ./build/desktop_probe

探针会短暂打开窗口并移动鼠标，检查实际堆叠、点击穿透、焦点、拖动、分裂、互动和置底后生殖；结束后恢复鼠标。它不加入 CTest，以免自动操作桌面。offscreen 测试只能检查 Qt 状态，不能替代原生输入验证；单实例与网络测试需要本地套接字权限。长时间与实际网卡测试命令见 验证记录。

代码结构

模块	职责
PetModel	行为、移动、进食、成长、摸摸、好感度与个体生殖冷却
FoodInventory	自然掉落、可用／预留库存、容量、消耗、退款与奖励
SwarmController	实体表、稳定编号、主实体保护、群体更新、分裂、生殖及上限
AnimationLibrary	共享动作缓存、PNG 图集、程序绘图和帧导出
PetWindow / CrackWindow	透明窗口、输入区域、层级、拖动与裂纹
ApplicationController	更新调度、菜单与面板、共享互动冷却、奖励结算及窗口生命周期
NetworkService / NetworkPanel	局域网发现、连接、保活、重连和设备面板
DispatchController / PetRenderState	派遣状态、返程确认、冻结恢复及访客绘制快照
SettingsStore / SingleInstance	存档、日志、单实例与召回
tests/	逻辑与集成回归、独立桌面及派遣探针

许可

代码采用 MIT，保留原作者 Copyright (c) 2026 jianghaichao。图片、生成算法及动作设计来自上游，Qt 与原 GDI+ 栅格化效果可能略有不同。Qt 是独立依赖，分发要求见 第三方说明。旧 C# 实现可从 Git 历史查看。