dsh-whale-live2d

Readme

# dsh-whale-live2d

把 DSH Web 右下角的**余额挂件**（`dsh-whale-widget`）从一张静态 PNG
换成 **Live2D 动态模型**（默认：DS 鲸鱼娘，44 表情 / 8 动作）。

## 为什么是「叠加式插件」

`dsh-whale-widget` 装在 `%DSH_HOME%\profiles\web\node_modules\` 里，
有两个硬约束：

1. 它由 `dsh plugin add github:MeteorNOX/DeepSeek-Balance-Whale-Widget` 安装，
   升级时会**覆盖**该目录 —— 任何直接改它的改动都会丢；
2. 它只认一张静态 PNG（`/dsh-whale/image.png`），内部没有任何 Live2D 支持。

所以本插件**不改挂件一个字节**，而是照 `dsh-whale-emote` 已验证的模式：

- 自己注册路由（`/dsh-live2d/*`）；
- 用挂件自己也在用的 `tapIndex` 机制注入一段客户端脚本；
- 客户端脚本把挂件那张 `<img>` **透明化**（但保留元素本身），
  在**完全相同的几何位置**叠一块 Live2D canvas。

保留 `<img>` 元素这一点很关键：挂件的命中测试是
`img.getBoundingClientRect()` + PNG alpha 取样（`isWhaleHit`），
元素一旦删除，`rect` 全为 0，挂件会**整个点不动、拖不动**。
保留它，则拖拽 / 吸附 / 气泡 / 音效 / 每轮消耗统计全部照旧。

## 依赖：Cubism Core 必须由你自己提供

Live2D 的专有许可**不允许再分发** `live2dcubismcore.min.js`，所以本插件不内置、
不代下。请从 Live2D 官方渠道获取（Cubism SDK for Web），放到：

```
%DSH_HOME%\pets\.runtime\live2dcubismcore.min.js
```

**没有它也不会坏**：挂件会**优雅降级**成原本的静态鲸鱼娘，页面上弹出一张
写明落点路径的安装指引卡。（渲染栈 pixi.js + Live2D 引擎是 MIT 许可，
已作为 `lib/live2d-vendor.js` 随本插件发布，无需另装。）

## 安装

```sh
# 从 GitHub（推荐）
dsh plugin --profile web add github:harmless0819-dev/dsh-whale-live2d

# 或从本地克隆
dsh plugin --profile web add link:<本仓库绝对路径>
```

装完**重启 `dsh web`**（Settings → 重启 DSH，或 `dsh-whale-emote\restart-web.ps1`
在**你自己的终端**里跑），然后浏览器 **F5**。

> 重启是必须的：插件的挂载声明（`cordis.patch.yml`）只在启动时读取。
> 装好之后，改 `lib/client.js` 只要 **F5**，不用再重启 —— 宿主路由每次请求都从磁盘读。

## 卸载

```powershell
dsh plugin --profile web remove dsh-whale-live2d
```

挂件会立刻回到原来的静态 PNG（本插件从未改动它）。

## 怎么确认装好了

三个层次，从粗到细：

```powershell
# 1. 宿主侧就绪状态（core 是否为 true 是决定性的一条）
curl http://127.0.0.1:3080/dsh-live2d/health.json

# 2. 模型本体可服务
curl -o NUL -w "%{http_code}" http://127.0.0.1:3080/dsh-live2d/asset/c_0120.moc3

# 3. 浏览器侧实况（F12 控制台）
#    window.__dshLive2d  → { state: 'ready' | 'core-missing' | 'error' | 'no-widget', ... }
```

`state` 的含义：

| state | 含义 |
|---|---|
| `ready` | 模型已上屏，PNG 已透明化 |
| `core-missing` | 缺 Cubism Core；静态挂件保持可见 + 指引卡 |
| `error` | 加载失败（`.detail` 有原因）；已退回静态挂件 |
| `no-widget` | 没找到 `.dshwv-body`（挂件被禁用或未加载） |

## 换成别的 Live2D 模型

模型目录是 `assets/whale-girl/`，由 `package-model.mjs` 生成。换模型时：

1. 把新模型的原文件放进 `_incoming/<你的模型>/`；
2. 改 `package-model.mjs` 顶部的 `SRC` / `EXPR` / `MOTION` 映射；
3. `node package-model.mjs`。

脚本会**断言**：源文件缺失、引用闭包不完整、或目录里残留非 ASCII 文件名
（宿主路由与 Live2D 清单只接受 `/^[A-Za-z0-9._-]+$/` 的路径段）都会**硬失败**，
不会静默产出一个加载不了的模型。

## 文件结构

```text
dsh-whale-live2d/
├── package.json             # DSH bundle 插件元数据
├── cordis.patch.yml         # 插件挂载声明
├── README.md                # 本文件
├── package-model.mjs        # 模型打包：ASCII 重命名 + 生成 model3.json 清单
├── test-harness.mjs         # 宿主侧离线自测（路由 / 穿越防护 / 模型完整性）
├── test-client.mjs          # 客户端离线自测（缺 Core 时优雅降级）
├── lib/
│   ├── index.js             # 宿主侧：路由 + 模型服务 + 注入
│   ├── client.js            # 客户端：把静态 img 换成 Live2D canvas
│   └── live2d-vendor.js     # pixi.js + Live2D 引擎（MIT，随包发布）
└── assets/
    └── whale-girl/          # 打包好的 Live2D 模型（3.95 MB，纯 ASCII 路径）
        ├── c_0120.model3.json
        ├── c_0120.moc3
        ├── c_0120.physics3.json
        ├── c_0120.cdi3.json
        ├── c_0120.2048/     # 贴图
        ├── motions/         # 8 个动作
        └── *.exp3.json      # 44 个表情
```

## 自测

```powershell
node D:\deepseek\dsh-whale-live2d\test-harness.mjs   # 27 项
node D:\deepseek\dsh-whale-live2d\test-client.mjs    # 11 项
```

两个都是离线跑（mock `ctx` / 最小 DOM 桩），不碰 profile、不启服务。必须保持全绿。

## 模型授权

DS 鲸鱼娘模型由 B站 **@氵六青**（11272072）无偿分享，作者声明：商用直播 √、
自印物料 √，**禁止盗用与出售**。

⚠️ **本仓库确实包含了模型文件**（`assets/whale-girl/`），以便插件开箱即用。
我们没有出售它，也不主张对它的任何权利；**若作者反对这一再分发，
`assets/whale-girl/` 会被移除** —— 缺模型时插件会优雅降级成静态挂件。

完整的第三方声明见 [`THIRD-PARTY-NOTICES.md`](./THIRD-PARTY-NOTICES.md)。
换用其他模型时请自行确认授权。