Skip to content

Partner v0.3.0

Choose a tag to compare

@github-actions github-actions released this 16 Nov 11:02
· 6 commits to master since this release

English | 简体中文 | 繁體中文

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 HitAreas uses 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. ParamAngleY for 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 only Core/live2dcubismcore.min.js and Core/LICENSE.md are extracted, into %LOCALAPPDATA%\Partner\pet\core\. A mismatch is refused, so an old or edited Core cannot reach the page's script-src.
  • Models — import a folder or a zip; a pack with several model3.json files asks which one. Only the files that model3.json references are copied, paths that escape the model folder are refused, .js is 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's notices/licenses/; THIRD-PARTY-NOTICES.md gains a Live2D section and names every new dependency (easy-live2d, Pixi.js 8, @pixi/sound 6 and their transitive packages).

Guards

  • .gitignore refuses *.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 .en and .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 Idle group, no physics and no HitAreas (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

  • PetAssetStore imports 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.
  • SettingsStore gains a monotonic Revision so the pet window can hot-reload the mapping, the dictionary and the timers without a restart; the feed endpoint reports speaking from VoiceHost.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.ts and ui/tests/pet-director.test.ts pin 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, multiple model3.json files, a Core hash mismatch and the ValidatePet boundaries.

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.