How stevenjoezhang/live2d-widget works
Project Type and Purpose
• This is a front-end widget library (no backend).
• Written in TypeScript, bundled with Rollup into “build/” and “dist/”.
• Purpose: embed a Live2D model (“waifu”) in any web page with minimal setup.
Main Architectural Layers
A. Development / Build Layer
• tsconfig.json, rollup.config.js, npm scripts
B. Transpilation & Bundling
• build/ (JS + d.ts outputs of src/)
• dist/ (final browser bundles: autoload.js, waifu-tips.js, waifu.css, JSON, chunks)
C. Runtime / Browser Layer
• autoload.js: inserted via <script> → loads waifu.css + waifu-tips.js
• waifu-tips.js: exposes initWidget(config)
• initWidget → core widget engine
Runtime Components & Interactions
1. Web Page
• User includes <script src="…/autoload.js">
• stylesheet <link> for waifu.css is injected
2. initWidget(config)
• Configurable paths: waifuPath (waifu-tips.json), cdnPath, cubism2Path, cubism5Path, tools[], drag, logLevel
3. Resource Loader
• Fetch waifu-tips.json (dialogue & selectors)
• Model version → dynamic import of either Cubism2 or Cubism5 core (from CDN or your dist)
4. Core Widget Engine
• widget.ts: orchestrates submodules
• Model Manager (model.ts) → loads model JSON + textures.cache
• Interaction Handlers:
– Drag Module (drag.ts)
– Tools Module (tools.ts) → buttons (screenshot, hide, next, etc.)
• Messaging Module (message.ts) → tooltip/dialog dialog manager
• Logger (logger.ts) → logLevel controls console output
5. External Services
• Optional: hitokoto.cn for random quotes
• CDN(s): jsDelivr or custom cdnPath for hosting resources
Build Pipeline
• src/ → tsc compile → build/
• build/ → rollup → dist/
• dist/:
– autoload.js (loader stub)
– waifu-tips.js (widget engine)
– waifu.css (styles)
– waifu-tips.json (default tips)
– chunk subfolder (if code-splitting enabled)
Important Patterns & Principles
• Modularity: each feature (drag, tools, message) is its own TS module.
• Dynamic loading: detect model version → lazy-load appropriate Core SDK.
• Separation of concerns: loader vs. engine vs. UI vs. rendering.
• Configurability: initWidget(config) as central extension point.