DyberPet: a PySide6 desktop pet with a JSON mod ecosystem and an unopened LLM layer

A pet you add with JSON, not a plugin you code

DyberPet is a desktop pet framework written in Python on top of PySide6, and its most interesting property is that the content is data. Characters, items, sound effects and mini pets are all extensible, and the extension path is JSON configuration. The project is explicit that it is not merely a GIF viewer, but a playable system with animation, interaction, raising, tasks and a shop, and that the mod freedom is the point.

The repository layout supports that reading. The top level holds DyberPet/, the code, alongside res/, the assets, docs/, langs.pro for translations, and run_DyberPet.py as the entry point. Inside res/ the structure is item and role based, and the changelog names the exact configuration files a mod author touches: the default coin definition sits in res/items/Default/items_config.json under coin, while a character's own coin UI configuration is read from res/role/PETNAME/pet_conf.json under coin_config. In other words the currency presentation is split between a global default and a per character override, and a mod can customise it without touching the framework.

The translation file and the per role directory are what make this a framework rather than a single application. A new character is a directory, a pet_conf.json and a set of animation frames, and the app reads it at runtime.

The Windows EXE is v0.10.3 while the runnable source stops at v0.6.7

This is the first thing to understand and it is easy to miss. The project status section states that the latest version is v0.10.3 and that the Windows build is packaged into the Release page, where you download and double click the EXE. Then the installation notes for Windows Terminal and for macOS both carry a qualifier: the source is open only up to v0.6.7.

So there are two distributions with different feature sets. The EXE has the newer work in it. The source tree you can run yourself stops at v0.6.7, and the changelog between those points is not empty. v0.6.7 adds a setting to switch off the speech bubble, v0.6.6 turns the inventory into draggable swappable slots and adds item cell positions to the save format plus an auto feed function, v0.6.5 adds an auto lock option that freezes HP and FV while the screen is locked, and v0.6.3 moves the coin name and icon configuration so mod authors can restyle currency per character.

For a reader deciding whether to adopt this, that gap is the deciding fact. If you need the current behaviour, you are on Windows and you take the EXE. If you want to read the code, extend it, or run it on macOS, you are looking at a version that is roughly four minor releases behind the packaged one, and the roadmap of the newer features is not something the older tree offers.

Building the conda environment the project expects

The Windows Terminal instructions tell you to create a fresh conda environment first, and the versions are pinned.

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 -i https://pypi.org/simple/
pip install pyside6==6.5.2
pip install tendo

The macOS variant is nearly the same, with one difference that matters: it pins pynput explicitly.

conda install -c conda-forge apscheduler
pip install pynput==1.7.6
pip install PySide6-Fluent-Widgets==1.5.4 -i https://pypi.org/simple/
pip install pyside6==6.5.2
pip install tendo

Once the environment exists, you download the repository and run the entry script.

run_DyberPet.py

Two dependencies explain the design. apscheduler is the scheduling layer behind the focus timers and the recurring pet tasks, and pynput is the global input hook that lets the pet react to clicks and drags anywhere on the desktop rather than only when its own window has focus. tendo is listed alongside them, and the PySide6-Fluent-Widgets package is what gives the application its Fluent style, including the custom theme colour option added in v0.4.3.

The mini pet follow queue and the anchor arithmetic behind it

The mini pet system is where the code shows its engineering, and the changelog documents it in unusual detail across several releases in 2024. Mini pets were originally called sub pets, and v0.4.4 renamed them properly. The follow behaviour was reworked repeatedly: v0.5.4 handled the screen edge case and the multi screen case, v0.5.5 made all mini pets queue so each one gets the correct anchor_x, with the queue updating and refilling when one pet stops following or is recalled. v0.5.4 also let you switch following on and off per mini pet, and opened the drop option to pets that have a follow attribute.

The detail that tells you the code was debugged rather than sketched is in v0.5.4: mini pets that follow only on the X axis, walking left and right and returning to the main character after being dragged away, plus a fix for vertical drift when the anchor multiplied by the scale factor did not land on an integer, and a forced reposition on pet switch to avoid a Qt internal error causing displacement. v0.5.0 added an independent minipet_scale setting so mini pets can be sized separately from the main character, and v0.5.3 lifted the limit of one summoned mini pet at a time.

For anyone writing a mod, the practical takeaway is that mini pets are not decoration. They are an ordered system with a follow flag, a scale, an anchor and a queue, and a mod that sets an anchor without understanding that geometry will produce a pet that drifts.

Hunger, affection, coins and a ladder that runs to two hundred levels

The pet keeping mechanics are the part that separates this from a floating GIF. A pet has hunger, an affection value, and coins, and the whole system is driven by a set of named behaviours you can configure per character.

The affection system was reworked in v0.6.4, when the level cap moved from 7 to 200, with every level requiring 120 affection points, and badge icons were added to the right click menu and the character panel, four of them, a star at level 1, a moon at 4, a sun at 16 and a crown at 64. The pat interaction was made hunger aware in v0.4.6, where pet_conf.patpat changed type to a dict mapping a fullness level to an animation name, and the interaction module then picks a pat animation at random based on the current fullness level.

Other behaviours are equally specific. The v0.6.1 release added random feed_required bubbles, and the v0.6.0 series built the speech bubble module from the framework up, including default configuration for every bubble behaviour, and bubbles triggered by patting during a focus session, plus a bubble when the pet is clicked seven or more times within one second. v0.5.7 merged overlapping notifications so that fullness, affection and item changes combine with the notification already on screen instead of stacking.

The save format is part of the contract. v0.6.6 added item cell positions to the archive format, and v0.5.0 reworked the save handling to avoid crashes and forced exits caused by save file problems, and v0.5.2 clears negative item counts during initialisation.

The AI assistant is announced but the module is not open

The README leads with three things, and the third one needs a caveat. The desktop pet system is the core, the AI assistant is the second headline, and the mod ecosystem is the third.

The project status section is where the caveat appears. It states that the large model module is still under active development and that the related capabilities are not yet fully open sourced. It also notes that the current repository content is primarily Chinese, that feedback is welcome through Issues, and that copy mirrors on CSDN and GitCode exist which are unrelated to this project, so the GitHub repository is the one to trust.

There is a fair reading in the project's favour. The README states the AI is an addition rather than a precondition, and that without it the pet experience is complete on its own. That is the correct framing, and it means the 0.6.7 source tree is a usable product without the LLM layer rather than a stub waiting for it.

What you cannot do today is read or extend the model integration. If your requirement involves a local model, a specific provider, or any kind of audit of what leaves the machine, this repository cannot answer that question, and you should treat the AI features as a roadmap item rather than a capability.

Where a mod author starts, and what the docs do not cover yet

Two developer entry points exist. For art, docs/art_dev.md covers building a new pet appearance and animation set on top of the existing functionality. For features, the documentation points back at the main README, and that document is marked as under construction. The user manual is also listed as under construction. The collection page, docs/collection.md, gathers the characters, item mods and mini pets that exist, with introductions and download links, and they are imported through the app.

So the documentation surface is uneven, and it is uneven in a way that matches the project. The art path is where the framework actually earns its keep, since a new character is data and the doc explains the data. The functional extension path is the weak spot, because the document that would explain how to add a new module is the same README you have already read, and it says the work is in progress.

There is also a naming collision to be aware of. The repository is called DyberPet, the entry point is run_DyberPet.py, and the conda environment in the instructions is named Dyber_pyside, while the in application terms the character is a pet, the smaller companions are mini pets, and the personality value is the affection level. Each has its own vocabulary, and a mod author reading the changelog will meet all of them.

Editorial conclusion

DyberPet fits a Windows user who wants a character on the desktop with pet keeping mechanics, a shop, focus timers and mini pets, and it fits mod authors who would rather configure a character in JSON than write plugin code. It does not fit a macOS or Linux user who wants the current feature set from source, because the open tree stops at v0.6.7, and it does not fit anyone who needs the AI assistant today, since the large model module is still under development and not fully open sourced. Check three things first. Check which version you are actually getting, because the Windows EXE in the latest release tag is v0.10.3 while the source you can run is v0.6.7,. Check the pinned dependency versions, since the environment is built around Python 3.9.18 with PySide6 6.5.2 and PySide6-Fluent-Widgets 1.5.4. And check the language of the content, since the repository is Chinese first with an English README alongside it. The last push was on 2026-10-16 and the license is GPL-3.0, so any code you take carries copyleft.

Frequently asked questions

Official sources

1. ChaozhongLiu/DyberPet on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases