zzz-desktop-companions

<div align="center">

<img src="apps/burnice/assets/icon.png" alt="Burnice" width="96"> <img src="apps/remielle/assets/icon.png" alt="Remielle" width="96">

ZZZ Desktop Companions

Burnice and Remielle as animated 3D desktop pets, with conversation and voice running on your own GPU.

</div>

Unofficial, non-commercial fan project. Not affiliated with, endorsed by, or connected to HoYoverse. Zenless Zone Zero and its characters belong to their respective owners. Full attribution for every model, texture, voice reference and dataset used here is in NOTICE.md — read it before redistributing anything from this repo.

Two Electron apps put a rigged 3D character on your desktop: transparent, always on top, click-through except where she actually is. Drag her around, toss her, talk to her. She answers in her own voice, changes expression, and gestures. Run both and they find each other, share one conversation and one control panel, and take turns.

Everything runs locally. A small FastAPI server on 127.0.0.1:17865 holds the models and both companions share it. There is no account, no API key, and nothing leaves the machine.

Quick start

git lfs install
git clone https://huggingface.co/william590y/zzz-desktop-companions
cd zzz-desktop-companions
git lfs pull

npm run setup     # checks Node, Python and your GPU; builds server\.venv; npm install
npm start         # starts the shared server, waits for it, launches both companions

The first npm start downloads about 6 GB of model weights and can take 20 minutes. Later starts are under a minute. If anything goes wrong, npm run doctor will tell you what.

Full walkthrough, VRAM guidance and troubleshooting: docs/SETUP.md.

Requirements

The server sizes itself to your card: under 12 GB it quantises the chat model to 4-bit, 12–24 GB keeps it resident in fp16, above 24 GB everything stays resident.

Commands

scripts\start-companions.cmd is a double-clickable wrapper for a desktop shortcut.

What's in here

zzz-companions/
  apps/burnice/      Electron app — src, assets (PMX model, textures, voice), tests
  apps/remielle/     Electron app — same shape
  packages/core/     @companions/core: modules both apps share, incl. the local server client
  server/            FastAPI GPU server: Qwen2.5-3B + LoRA, Qwen3-TTS, faster-whisper
  models/            The shipped LoRA adapters and their model cards
  training/          How those adapters were produced (cluster-era, kept for provenance)
  scripts/           setup, start, stop, doctor
  docs/              the documents below

Docs

• docs/SETUP.md — clone to first run, VRAM tiers, troubleshooting
• docs/ARCHITECTURE.md — the two apps, the named-pipe room, the shared panel, the shared GPU server, and what a chat turn and a voice turn actually do
• docs/PORTING.md — this used to run on a 48 GB A6000 over SSH and Slurm; what the move to one desktop card gained and what it cost
• docs/models.md — the adapters, how they were trained, how to load them
• docs/local-worker-integration.md — wiring an app to the local server
• docs/PHYSICS.md — secondary motion, the Jiggle physics setting, and verification
• docs/PUBLISHING.md — review and upload both companions to the existing Hugging Face repository
• NOTICE.md — attribution and licensing for every third-party asset and model

Status and limits

• Both companions share one server process. A second one is not supported — a 16 GB card cannot hold two copies of the models. Group replies therefore serialise.
• training/ is provenance, not a runnable pipeline: it still assumes Slurm and cluster paths.
• Speech recognition loads independently of conversation and is allowed to fail on its own; if it does, typed chat and spoken replies keep working.
• With no server reachable at all, the pets still run, greet, gesture and use their pre-rendered voice lines. You lose conversation, not the companion.