Repository navigation
Partner v0.3.0
Partner v0.3.0
A desktop pet, built on Live2D. A small transparent window that stays on top of everything, reads the assistant replies as they are finalised, scores them against a keyword dictionary, and plays a fixed set of scenes — greet, stretch, head-pat, nod, lip-sync, sleep. It does not talk to the model, does not change the system prompt, and does not ask the model for an emotion tag.
The pet
- Where it lives — its own window: transparent, borderless, always on top, out of the taskbar, not resizable. Settings → Desktop pet holds the on/off switch, click-through, motion sound, scale and a "reset position" button.
- What drives it — two trigger kinds only: local interaction (click on head/face/body, hover, drag, double click, idle timeout) and a keyword match in a finished reply. Fifteen scenes in total, each an action combination plus an expression, with a priority order so a double click interrupts an idle stretch instead of queueing behind it.
- Click zones — a model with
HitAreasuses them; a model without gets head/face/body proportions cut from its bounding box, adjustable with two sliders. - Actions fall back — an abstract action resolves through the model's mapping table first, then procedural parameter keyframes (e.g.
ParamAngleYfor a nod), then is skipped. Not every model carries every motion, so the fallback is what makes an arbitrary model usable. - Lip-sync without audio — TTS plays on the .NET side and the WebView never receives the stream, so the mouth is a 6–9 Hz envelope while the backend reports speaking. It looks like talking, it is not phoneme-accurate.
- Emotion from text — a keyword dictionary with weights, longest-match-first, negation prefixes (
不开心is not开心), and a try-out box in settings that scores a pasted sentence with the same code the pet runs. Four emotions: smile, angry, cry, shy. Default words are editable per emotion, up to 200 each, weight 1–10.
The Core and the models are yours
- Cubism Core — download Cubism 5 SDK for Web R5 yourself from Live2D's site and import the zip under Settings → Desktop pet. The import is strict: the whole-file SHA-256 must be
67064a7f…df06ba0, and onlyCore/live2dcubismcore.min.jsandCore/LICENSE.mdare extracted, into%LOCALAPPDATA%\Partner\pet\core\. A mismatch is refused, so an old or edited Core cannot reach the page'sscript-src. - Models — import a folder or a zip; a pack with several
model3.jsonfiles asks which one. Only the files thatmodel3.jsonreferences are copied, paths that escape the model folder are refused,.jsis refused, and the caps are 200 MB / 2000 files. Chinese file names in a zip without the UTF-8 flag are decoded as GBK, so older packs work. Model copyright belongs to each author; the app grants you nothing. - Where it goes — everything stays under
%LOCALAPPDATA%\Partner\pet\. Nothing is uploaded.
Licence
- Live2D code is not MIT. The app's own code still is. easy-live2d bundles the Live2D Cubism Framework, which is under the Live2D Open Software License — a separate agreement, not an MIT-compatible one. The Framework's copyright notice is preserved in the built pet bundle by a banner, because a minifier would otherwise drop it and the licence forbids removing it.
- Models keep their authors' rights. No model ships with the app and none is mirrored.
- Both licence texts ship with the source in
third-party/and are copied into the installer'snotices/licenses/;THIRD-PARTY-NOTICES.mdgains a Live2D section and names every new dependency (easy-live2d, Pixi.js 8, @pixi/sound 6 and their transitive packages).
Guards
.gitignorerefuses*.moc3,**/live2dcubismcore*.js,ui/public/Core/,ui/public/Resources/and*.model3.json, so a model or a Core cannot be committed by accident.- The release workflow runs
git ls-files '*.moc3' '*live2dcubismcore*' '*.model3.json'before the frontend build and fails when the output is non-empty — the ignore file is the habit, the check is the guarantee. doc/pet.md(with.enand.zh-TW) documents getting the Core, importing a model, the scene table, the default dictionary, the licence rules and the known limits.
Upgrading
- Install v0.2.2 or later directly, or let the previous version update itself.
- Nothing existing changes: settings, sessions, the memory database, downloaded engines and the desktop-control contracts are untouched. The pet's settings are a new section, empty until you open the page.
- No new listening port and no new permission. The pet window's capability file grants only move, resize, read the cursor and toggle click-through.
- If you had a model or a Core sitting under
ui/public/, it is now ignored by git; the app reads them from%LOCALAPPDATA%instead, through the import page.
Limits
- The mouth is procedural — there is no audio in the WebView, so lip-sync is an envelope, not phonemes.
- Procedural fallbacks are approximations — a model without the expected parameters gets a shallower version of a scene, or none. A model with no
Idlegroup, no physics and noHitAreas(the sample model is one) relies on the fallbacks for most scenes. - Multi-monitor and scaling smoke is partial — position restore checks that the stored point is on a visible screen and otherwise moves to the main display's bottom right; 125% / 150% scaling and a secondary screen with negative coordinates still need a manual pass.
- Sound is opt-in — motion sound is off by default.
- A model that is missing at start-up leaves the window blank and reports the reason to the settings page instead of raising a dialog.
Engineering
PetAssetStoreimports both the Core and the models: the Core by whole-file hash, the models by parsing the zip central directory for raw entry names (the BCL mangles GBK names, verified) and copying only referenced files through a temporary directory and an atomic rename.SettingsStoregains a monotonicRevisionso the pet window can hot-reload the mapping, the dictionary and the timers without a restart; the feed endpoint reportsspeakingfromVoiceHost.IsSpeaking, which only reads the state the voice pipeline already tracks.- The emotion matcher and the scene director are pure modules with an injected clock and random source, so
ui/tests/pet-emotion.test.tsandui/tests/pet-director.test.tspin the tie-breaking rules, the negation handling, priority pre-emption and the once-a-day greeting without a running pet. - The API tests cover zip-slip,
.., absolute paths, reparse points,.js, size limits, a GBK-named zip, multiplemodel3.jsonfiles, a Core hash mismatch and theValidatePetboundaries.
The voice engines are downloaded from the engines-v1 release on first use; their URLs and SHA-256 are pinned in this build. The app code is MIT licensed; the engine runtimes and model weights keep their own licences, see THIRD-PARTY-NOTICES.md in the release assets.