dsh-whale-intro

Readme

# dsh-whale-intro 🐋

给 DSH 的一个**开场**：加载页面时鲸鱼娘先在海里出现，**挥手 → 眨眼**，然后随着界面淡入沉回背景里。

和「播一段视频再淡出」的区别在于**时机**：

| | 普通的启动视频插件 | 本插件 |
|---|---|---|
| 什么时候出现 | 界面已经渲染出来之后，再盖一层上去 | 在界面的启动页出现之前就占住屏幕 |
| 怎么接进界面 | 视频放完 → 淡出 → 露出界面（中间必然有一次"切"） | 她一边沉下去，界面一边浮上来，是同一个动作 |

原理：客户端插件的浮层永远晚一步——DSH 的启动页是内核在 shell 脚本里同步建出来的。
只有往 `<head>` 里插一行**解析阻塞脚本**才能抢在它前面，这也是本插件把动画放在
Host 半侧、通过 `webserver/index-inject` 注入的原因。

## 行为

- 她出现时是**淡淡的浮入**（透明度 + 轻微上浮），不是"啪"地弹出来。
- 站着的时候有**缓慢的浮动 + 轻微摆动**（不是因为素材是动图，是 CSS 让她活着）。
- **2.3 秒时交叉淡入到眨眼那张**——两张是同角度的站姿立绘，所以看起来像一个小动作，不像跳帧。
- **点一下、按任意键、滚一下滚轮**，立刻跳过（0.42 秒的快速淡出）。
- 界面就绪（内核启动页消失 + `#root` 有内容）之后才交接；最早 3.4 秒、最晚 6 秒，
  两个边界都是硬的：界面再慢也不会被她挡住。
- **开场期间会把内核自己的启动页按住**（`[data-dsh-boot]{opacity:0}`）。它由 shell 脚本
  在运行时创建，排在覆盖层**后面**——不按住的话同层级下它会盖在她上面，就又变成
  "先闪一下白底加载卡"了。交接时这条规则会一起撤掉。
- 素材请求失败、脚本抛错、**素材 1.5 秒内解不出来**、标签页后台被节流——
  **任何一条路都是立刻放行**，不是卡住。
- 同一标签页内**一次启动只演一遍**（刷新不重播）。想看：地址后面加 `?whaleintro=1`；
  想临时关掉：`?whaleintro=0`。
- 进场层挂在 `document.documentElement` 上，**不进 `#root`**，所以不会干扰 React 挂载。

## 为什么现在是清楚的

之前那版播的是一段 **640×360** 的视频，其中她本人只占约 **262×308** 像素；按窗口高度
58% 显示时相当于放大约 1.5 倍，所以发糊——编码怎么调都救不回来（实测换 hqx、换
libplacebo 的 ewa_lanczossharp 都更差或只是更"干净"）。

现在用的是两张 **512×512 带透明通道的立绘**，按 58% 显示时约 522px，**基本是原生 1:1**，
所以发丝、荷叶边、围裙上的小鲸鱼都是清楚的。透明通道还顺手解开了一个限制：她身上不再带
黑色底，所以尺寸上限从 0.62 放宽到 0.95，想放多大放多大（超过 512px 会开始软）。

## 安装

### 桌面版（DSH Desktop，profile 名 `desktop`）

官方桌面版的市场只收 **npm 上已发布的精确版本**，GitHub 仓库装的插件在市场里点不了；
但桌面版**自带 CLI 的 plugin 子命令对 desktop profile 放行**，直接用它：

```powershell
# 把 <你的 DSH 安装目录> 换成实际路径，例如 E:\DSH
$dsh = "<你的 DSH 安装目录>\resources\runtime\cli\bin\dsh.cmd"

# ① 直接从 GitHub 装（需要能访问 github.com）
& $dsh plugin --profile desktop add "https://github.com/xulianglong-akk/dsh-whale-intro"

# ② 或者先下载到本地目录，再按目录装（路径里不要有空格）
& $dsh plugin --profile desktop add "D:\DSH\plugins\dsh-whale-intro"
```

装完**完全重启 DSH**（bundle 层是启动时装配的）。

> 卸载：`& $dsh plugin --profile desktop remove dsh-whale-intro`，
> 然后手工删掉残留链接 `cmd /c rmdir "<profile>\node_modules\dsh-whale-intro"`
> ——留着它下次启动可能被重新挂载（两层同 id 会产出两条 entry）。

### 旧版 `dsh web`（profile 名 `web`）

```powershell
dsh plugin --profile web add "https://github.com/xulianglong-akk/dsh-whale-intro"
```

### 改代码后要不要重启，看改的是哪半边

| 改的东西 | 生效方式 |
|---|---|
| `src/intro.js`（屏幕脚本）、`assets/*` | **刷新页面**即可（每次渲染索引都从磁盘重读） |
| `entry.js`（Host 半侧：路由、注入内容） | **必须完全重启 DSH**（一个进程只导入一次） |
| profile 里 `cordis.patch.yml` 的配置覆盖行 | 刷新（补丁层热重载） |

> 改了 `entry.js` 之后、重启之前，开场是**不显示**状态（不是坏了）。

## 配置

改 profile 的 `cordis.patch.yml`，加一条按 id 定位的覆盖行（不用改本包）：

```yaml
- id: dsh-whale-intro
  name: dsh-whale-intro
  config:
    enabled: true          # false = 完全不注入，回到 DSH 原生启动页
    oncePerLaunch: true    # false = 每次刷新都演一遍
    minMs: 3400            # 最早交接时间（毫秒）
    maxMs: 6000            # 最晚交接时间（毫秒）
    poseMs: 2300           # 第几毫秒交叉淡入到第二张（眨眼）
    sizeVh: 0.58           # 她占窗口高度的比例
    maxHeightPx: 620       # 她的高度上限（px），高窗口想让她更大就调这个
```

### 不改任何文件就能试参数（地址栏）

这些参数只影响这一次打开，**优先级高于配置**，适合先试出来再写进配置：

| 参数 | 作用 | 取值范围 |
|---|---|---|
| `?whaleintro=1` / `=0` | 强制演一遍 / 这次不演 | — |
| `?whalesize=0.5` | 她占窗口高度的比例（默认 0.58） | 0.2 – 0.95 |
| `?whalemax=900` | 她的高度上限（px，默认 620） | 160 – 1600 |
| `?whalepose=1500` | 第几毫秒切到眨眼（默认 2300） | 400 – 20000 |
| `?whalemin=2000` | 最早交接时间（毫秒，默认 3400） | 0 – 20000 |
| `?whalemaxms=4000` | 最晚交接时间（毫秒，默认 6000） | 1000 – 30000 |

例如"大一点、眨眼早一点"：`?whaleintro=1&whalesize=0.7&whalepose=1400`。

## 换素材

`assets/pose-1.webp`（挥手）和 `assets/pose-2.webp`（眨眼）就是全部内容。要求：

- **带透明通道**的 WebP / PNG（本插件也会发 `.gif` `.avif`）；
- 两张**同角度、同比例、同位置**最好——不然交叉淡入会看起来像跳帧；
- 换完**刷新页面**即可，不用重启（路由按文件大小 + 修改时间自动换 URL）。

想只用一张：把 `entry.js` 里的 `POSES` 数组删到只剩一个文件名即可（那时不会交叉淡入）。

## 本地预览（不装进 DSH 也能看）

双击 `preview.html`，就是一遍完整的开场（含跳过与重播按钮）。

## 结构

```
entry.js             Host 半侧：素材路由（白名单 + Range）+ <head> 注入
src/intro.js         注入进 <head> 的进场层脚本（每次渲染索引时重新读取）
assets/pose-1.webp   鲸鱼娘·挥手（512×512，透明）
assets/pose-2.webp   鲸鱼娘·眨眼（512×512，透明）
cordis.patch.yml     让 DSH 认识本插件的挂载声明
NOTICE.md            素材来源与许可（务必保留）
preview.html         本地预览
```

## 素材来源

立绘来自 [Sutera-Diffusus/dsh-whale-musume](https://github.com/Sutera-Diffusus/dsh-whale-musume)（MIT），
只改名未改动。角色与立绘归原作者所有，详见 `NOTICE.md`。