鲸鱼娘开场 xulianglong-akk/dsh-whale-intro

dsh-whale-intro 🐋

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

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

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

原理：客户端插件的浮层永远晚一步——DSH 的启动页是内核在 shell 脚本里同步建出来的。
只有往 里插一行解析阻塞脚本才能抢在它前面，这也是本插件把动画放在 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 放行，直接用它：

把 <你的 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）

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 定位的覆盖行（不用改本包）：

- 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）+ 注入 src/intro.js 注入进 的进场层脚本（每次渲染索引时重新读取） 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（MIT），只改名未改动。角色与立绘归原作者所有，详见 NOTICE.md。