# stevenjoezhang/live2d-widget architecture

> Architecture diagram of the GitHub repository stevenjoezhang/live2d-widget, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stevenjoezhang/live2d-widget
- Repository: https://github.com/stevenjoezhang/live2d-widget

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "Build-Time"
    tsconfig["tsconfig.json"]:::build
    rollup["rollup.config.js"]:::build
    pkg["package.json"]:::build
    src["src/"]:::build
    buildDir["build/"]:::build
    distDir["dist/"]:::build
    tsconfig -->|"compile"| buildDir
    rollup -->|"bundle"| distDir
    src -->|"tsc compile"| buildDir
    buildDir -->|"rollup bundle"| distDir
  end

  subgraph "Load-Time"
    autoload["autoload.js"]:::loader
    cssInject["inject waifu.css"]:::loader
    waifuBundle["waifu-tips.js"]:::loader
    autoload -->|"loads"| waifuBundle
    autoload -->|"injects"| cssInject
    waifuBundle -->|"calls initWidget(config)"| orchestrator
  end

  subgraph "Run-Time"
    orchestrator["initWidget()"]:::loader
    resourceLoader["Resource Loader"]:::loader
    modelMgr["Model Manager"]:::render
    renderer["Renderer"]:::render
    cubismCore["Cubism Core"]:::render
    dragMod["Drag Module"]:::ui
    toolsMod["Tools Module"]:::ui
    messaging["Messaging Module"]:::ui
    loggerMod["Logger Module"]:::ui
    externalCDN["CDNs / APIs"]:::external
    dataFile["waifu-tips.json"]:::external
    canvas["WebGL Canvas"]:::external
    consoleOut["console"]:::external

    orchestrator -->|"invoke"| resourceLoader
    resourceLoader -->|"fetch JSON"| dataFile
    resourceLoader -->|"dynamic import"| cubismCore
    resourceLoader -->|"create model"| modelMgr
    modelMgr -->|"provide data"| renderer
    renderer -->|"draw"| canvas
    dragMod -->|"user events"| renderer
    toolsMod -->|"buttons events"| renderer
    messaging -->|"show tooltips/dialogs"| canvas
    loggerMod -->|"logLevel info"| consoleOut
    externalCDN -->|"host SDK"| cubismCore
  end

  %% Click Events
  click src "https://github.com/stevenjoezhang/live2d-widget/tree/master/src/"
  click tsconfig "https://github.com/stevenjoezhang/live2d-widget/blob/master/tsconfig.json"
  click rollup "https://github.com/stevenjoezhang/live2d-widget/blob/master/rollup.config.js"
  click pkg "https://github.com/stevenjoezhang/live2d-widget/blob/master/package.json"
  click buildDir "https://github.com/stevenjoezhang/live2d-widget/tree/master/build/"
  click distDir "https://github.com/stevenjoezhang/live2d-widget/tree/master/dist/"
  click autoload "https://github.com/stevenjoezhang/live2d-widget/blob/master/dist/autoload.js"
  click waifuBundle "https://github.com/stevenjoezhang/live2d-widget/blob/master/dist/waifu-tips.js"
  click cssInject "https://github.com/stevenjoezhang/live2d-widget/blob/master/dist/waifu.css"
  click dataFile "https://github.com/stevenjoezhang/live2d-widget/blob/master/dist/waifu-tips.json"
  click orchestrator "https://github.com/stevenjoezhang/live2d-widget/blob/master/src/index.ts"
  click orchestrator "https://github.com/stevenjoezhang/live2d-widget/blob/master/build/index.js"
  click resourceLoader "https://github.com/stevenjoezhang/live2d-widget/blob/master/src/widget.ts"
  click resourceLoader "https://github.com/stevenjoezhang/live2d-widget/blob/master/build/widget.js"
  click modelMgr "https://github.com/stevenjoezhang/live2d-widget/blob/master/src/model.ts"
  click modelMgr "https://github.com/stevenjoezhang/live2d-widget/blob/master/build/model.js"
  click cubismCore "https://github.com/stevenjoezhang/live2d-widget/tree/master/src/cubism2/"
  click cubismCore "https://github.com/stevenjoezhang/live2d-widget/tree/master/build/cubism2/"
  click cubismCore "https://github.com/stevenjoezhang/live2d-widget/tree/master/src/cubism5/"
  click cubismCore "https://github.com/stevenjoezhang/live2d-widget/tree/master/build/cubism5/"
  click dragMod "https://github.com/stevenjoezhang/live2d-widget/blob/master/src/drag.ts"
  click dragMod "https://github.com/stevenjoezhang/live2d-widget/blob/master/build/drag.js"
  click toolsMod "https://github.com/stevenjoezhang/live2d-widget/blob/master/src/tools.ts"
  click toolsMod "https://github.com/stevenjoezhang/live2d-widget/blob/master/build/tools.js"
  click messaging "https://github.com/stevenjoezhang/live2d-widget/blob/master/src/message.ts"
  click messaging "https://github.com/stevenjoezhang/live2d-widget/blob/master/build/message.js"
  click loggerMod "https://github.com/stevenjoezhang/live2d-widget/blob/master/src/logger.ts"
  click loggerMod "https://github.com/stevenjoezhang/live2d-widget/blob/master/build/logger.js"
  click src "https://github.com/stevenjoezhang/live2d-widget/blob/master/src/icons.ts"
  click src "https://github.com/stevenjoezhang/live2d-widget/blob/master/build/icons.js"
  click src "https://github.com/stevenjoezhang/live2d-widget/blob/master/src/utils.ts"
  click src "https://github.com/stevenjoezhang/live2d-widget/blob/master/build/utils.js"

  %% Styles
  classDef build fill:#eeeeee,stroke:#888888
  classDef loader fill:#cce0ff,stroke:#204a87
  classDef render fill:#dff0d8,stroke:#3c763d
  classDef ui fill:#fcf8e3,stroke:#8a6d3b
  classDef external fill:#f2dede,stroke:#a94442,stroke-dasharray:5 5
```
