BandoriPet: a Live2D desktop pet built on PySide6 and a LuaJIT renderer

What BandoriPet actually solves

Most desktop pets are either a static sprite that bounces around a window or a commercial product tied to one vendor's runtime. BandoriPet targets a narrower audience: people who want BanG Dream! characters animated on their own desktop, with the chat behaviour driven by a language model they configure themselves. The README frames the appeal directly, describing a desktop that turns into a CiRCLE rehearsal room, and lists 51+ characters and 305+ outfits.

The feature list goes past decoration. There is an LLM roleplay layer with a per-character System Prompt and an affinity memory system, so replies change as you interact. There is optional TTS through a local Qwen3TTS backend with mouth-shape sync, optional ASR through a local faster-whisper backend or an OpenAI-compatible endpoint, a system tray, always-on-top frameless windows, and multi-character display. A local webhook port accepts forwarded messages from QQ, WeChat, Telegram or Discord bots.

That combination is the actual pitch. You are not installing a wallpaper. You are installing a small runtime that holds Live2D models, a chat pipeline and optional speech in and out, and you are expected to supply API credentials for whichever LLM backend you choose. If you only want a moving picture on your screen, the setup cost here is out of proportion to what you get.

The LuaJIT render core and the Python shell around it

The rendering path is the part that separates this project from typical PySide6 pets. Instead of drawing Live2D through live2d-py, BandoriPet uses a self-developed LuaJIT core built on Live2D-v2-Lua, which the README credits to the same author. The claim in the README is a performance improvement of 6x or more over live2d-py, described as 30fps to 180fps+. That number comes from the project's own documentation, not from an independent measurement, and the README does not state the hardware or scene it was measured on.

The architecture follows from that choice. Python 3.10+ runs the application: PySide6 for windows and the Fluent settings panel, PyOpenGL for the GL surface, and the lupa package as the bridge into LuaJIT. The Lua side handles model deformation and motion, which is why the repository carries a custom_hit_area_state.lua and a click_motion_presets.py alongside the Python modules. Model packages ship either as a zstd-compressed stream (about 900MB, loaded without extracting to disk) or as a traditional 7z archive (about 4GB, extracted to models/). The zstd path needs the zstandard package, which is in requirements.txt.

Around that core sits a fairly large Python surface: chat_runtime.py, character_persona_manager.py, emotion_behavior.py, asr_manager.py, companion_server.py, bandori_mcp_server.py and filesystem_mcp_server.py are all top-level entries. The MCP and Computer Use features are what those servers serve. This is not a thin wrapper; it is a multi-process desktop application, and the repository layout shows it.

Installing BandoriPet and running it the first time

The README's quick start has five steps. Clone the repository, download the model pack, create a virtual environment, install dependencies, then run main.py. The README explicitly recommends a virtual environment to avoid conflicts with system Python packages.

Start with the clone and the virtual environment:

git clone https://github.com/HELPMEEADICE/BANDORI-PET-REV.git
cd BANDORI-PET-REV
python -m venv venv

Activate it. On Windows the README gives `venv\Scripts\activate`; on Linux and macOS it is `source venv/bin/activate`. After activation the prompt shows `(venv)`.

Then install the Python dependencies:

pip install -r requirements.txt

The model pack is a separate download and is marked as required. The README points to ModelScope, Google Drive and Baidu Netdisk for both the zstd stream package and the 7z archive. After downloading, models/ goes into the project root. For the 7z package the expected layout is a models/ directory containing per-character folders such as kasumi, yukina, anon and tomorin.

Two dependencies are installed from source rather than from PyPI. The README requires the PySide6 branch of PyQt-Fluent-Widgets, and Live2D-v2-Lua is cloned but not pip-installed:

mkdir third_party
git clone -b PySide6 --single-branch https://github.com/zhiyiYo/PyQt-Fluent-Widgets.git third_party/PyQt-Fluent-Widgets
pip install -e third_party/PyQt-Fluent-Widgets
git clone https://github.com/EasyLive2D/Live2D-v2-Lua.git third_party/Live2D-v2-Lua

Finally, launch it:

python main.py

The README does not describe what the first window looks like or what a successful launch prints, so there is no expected console output to compare against. If the GPU path misbehaves, the README gives one diagnostic switch: setting `BANDORI_GPU_ACCELERATION=0` forces software rendering instead of Qt hardware OpenGL.

macOS and Wayland are not the same install

The README treats macOS and Wayland as separate paths rather than variations of the main one, and the reasons are concrete.

On macOS, the PyPI lupa wheel does not include lupa.luajit21, which the Live2D core needs. The README therefore directs macOS source users to a dedicated script after the third-party dependencies are in place:

bash installer/macos/install_source_dependencies.sh

That script installs the regular dependencies, compiles LuaJIT 2.1 and applies an image byte-stream patch to Live2D-v2-Lua. The README states the script prints `OK: LuaJIT 2.1...` only on success, and warns against running it with sudo because the virtual environment or config.json can end up owned by root.

On Wayland the constraint is stricter. The layer-shell bridge must use exactly the same Qt minor version as the system Qt and PySide6, and the PyPI PySide6 wheel cannot be used. Wayland users are told to install from requirements-linux-wayland.txt and follow docs/WAYLAND_NATIVE.md for Qt Wayland, LayerShellQt, the KWin or GNOME companion and the bridge build. The README states the application will not fall back to XWayland in a Wayland session. Native support is listed for Plasma 6, GNOME 46+ and Hyprland.

That is a real maintenance surface. A Qt minor-version bump on your distribution can break the bridge until you rebuild it, and the README offers no XWayland escape hatch.

Where BandoriPet is the wrong choice

The model pack is the first hard limit. The recommended zstd package is roughly 900MB and the 7z alternative roughly 4GB before extraction. Neither is bundled with the repository, and the README does not document a mirror beyond the three channels it lists. If your network cannot reach ModelScope, Google Drive or Baidu Netdisk, the quick start stops at step three.

The second limit is the runtime. This is a source-run Python application with a compiled LuaJIT component and a source-built Fluent Widgets fork. There is no packaged release artifact described in the README, and the releases listed for the project are version tags (v3.1.4, v3.1.3.5, v3.1.3) rather than a documented installer. If you want a double-click install for a non-technical user, this is not that project today.

The third is scope. The LLM roleplay, TTS and ASR features all depend on external backends you must supply: an API configuration for the language model, a Qwen3TTS server the README says listens on http://127.0.0.1:9880/ by default, or a faster-whisper install. Without those, you get the Live2D pet and the pixel-mode pet, which is a much smaller product than the feature list suggests.

Finally, the README carries a disclaimer that the project is for learning and exchange, that character model copyright belongs to the original authors and rights holders, and that commercial use is not permitted. If your intended use is commercial, the project itself tells you to stop.

How it differs from live2d-py based pets

The obvious alternative is a desktop pet built directly on live2d-py, the Python Live2D binding the README compares against. The difference is the rendering layer. A live2d-py pet drives model deformation from Python, so motion and draw calls share the interpreter with the UI code. BandoriPet moves that work into LuaJIT through lupa and keeps Python for windows, chat and settings. The README's own figure for that change is a move from 30fps to 180fps+, which is the project's claim rather than a measured result.

The second difference is breadth. A typical live2d-py pet is a window, a model and a menu. BandoriPet adds a persona manager, an affinity memory store, an emotion behaviour layer, TTS with mouth sync, ASR input, a webhook server for chat platforms, and MCP servers for file and browser tooling. Those are separate subsystems, and each one is another thing that can fail independently of the renderer.

The trade-off is legibility. If you want to read the whole program in an afternoon, a small live2d-py script wins. BandoriPet's top-level directory holds dozens of Python modules plus a Lua layer, and the setup path forks by platform. Choose it for the feature set, not for simplicity.

Licence, maintenance and upgrade cost

The code is GPL-3.0, per the repository licence file and the badge in the README. That matters if you plan to redistribute a modified build: GPL-3.0 carries copyleft obligations, and the project's own DISCLAIMER.md adds a separate restriction on the character models, which the README says belong to their original authors and rights holders and must not be used commercially. Code licence and asset permission are two different questions here, and the README answers them separately. This is not legal advice; read LICENSE and DISCLAIMER.md yourself.

Maintenance looks current rather than dormant. The repository is not archived, and the last push was on 2026-09-15. The most recent tagged release is v3.1.4 from 2026-07-08, described as a bug-fix and i18n release, with v3.1.3.5 and v3.1.3 before it in the same month. The README documents nine interface languages and a model import path, so a version bump can touch translation files, character data and the Lua bytecode build.

Upgrade cost centres on the model pack and the platform bridge. setup.py builds bytecode into BUILD/.luajit-bytecode and defines a managed-files manifest, and the Windows installer defaults to code page 936 with a BANDORIPET_MSI_CODEPAGE override, which tells you packaging is treated as a real target. But the documented install path is still source-based, and on Wayland any Qt minor change means rebuilding the layer-shell bridge. Budget for that if you run Plasma 6 or Hyprland.

Editorial conclusion

Adopt BandoriPet if you want a Live2D desktop companion with LLM roleplay and you are comfortable running Python 3.10+ from a virtual environment, downloading a model pack in the hundreds of megabytes, and treating the character art as non-commercial. Skip it if you need a packaged binary, a small install, or a Wayland session without the Qt minor-version matching described in docs/WAYLAND_NATIVE.md. Before installing, confirm your GPU exposes OpenGL 3.3+, check that models/ sits at the project root, and read DISCLAIMER.md and the GPL-3.0 terms for the code.

Frequently asked questions

Official sources

1. HELPMEEADICE/BANDORI-PET-REV on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases