# 礼物特效

[English](./gift-effects.md) | [中文](./gift-effects.zh-CN.md)


礼物特效：把礼物动画叠在对话区上，并飘出一条送礼提示弹幕。总开关默认关闭，**素材入库即可用**——不需要先绑定任何礼物。

## 总览

礼物特效由三层组成：

- **素材库**——本地素材库（SVG / SVGA / 图片），带文件夹、权重与 manifest，落在 `$DSH_HOME/danmaku-gifts/`。
- **礼物目录**——B 站礼物清单（名称 / ID / 价格 / 图标），用于左列选择；内置一份离线目录，也可用你自己的房间号提取合并。
- **特效位置**——把「礼物」对应到一张素材卡，设置落点；触发时播放动画并叠加一条提示弹幕。

礼物特效与弹幕渲染共用同一覆盖层：特效在独立的 `.dsh-gift-layer` 上播放，不拦截鼠标事件；提示弹幕走普通弹幕轨道。

新装首次启动会播种 **3 张默认礼物卡**（礼物目录随包内置、离线可用；但导入每张卡的动画素材需要联网，离线时会跳过 —— 即 0 卡，可稍后手动重试）：

| 礼物 | ID | 卡权重（= 触发概率系数） |
|---|---|---|
| 牛哇牛哇 | 31225 | 0.7 |
| 人气票 | 34391 | 1 |
| 干杯 | 31116 | 0.2 |

## 入口

设置 → 插件 → 插件配置 →「弹幕 Live Chat」卡片，滚到 **礼物** 区段：

- **启用礼物特效**（`giftEnabled`）——礼物模块**自身**的总开关，**默认关闭**；插件总开关（`enabled`）关闭时礼物模块同样停摆。
- **打开礼物配置…**——唯一的入口按钮，打开大模态（左礼物库 + 中素材库 + 右配置）。

也可在设置左侧导航点「礼物」Tab（紧跟在「弹幕库」之后）。大模态 `min(1280px, 96vw)` × `min(760px, 88vh)`，横向三栏：

- **左栏（礼物库）**——顶部一行：**搜索框在左**、**单个分类下拉在右**（点开一个浮窗，父级 bilibili / 自定义与 bilibili 的金瓜子 / 银瓜子子级同在其中）；下方是清单；bilibili 行是「+」/红色「×」，自定义行只有红色「×」（删除素材）（248px 起，200–400）。
- **中栏（素材库）**——本地素材面板，顶部一行工具条，下方是自适应素材网格。
- **右栏（配置）**——特效位置 / 基础 / 测试三段（300px 起，240–420）。

两条栏间分界线**可以拖动**改宽窄；宽度写入本地存储（键 `dsh-gift-pane-layout-v1`），**刷新页面、重开窗口、重启 dsh 后都保持**。没有右侧锚点导航条，也不再是单页四段。

## 素材库（中栏面板）

中栏是本地素材库主界面，顶部一行工具条，下方是素材网格：

- **工具条**——房间号输入框（**无标签**，仅占位符提示）+「提取」｜「导入文件…」+「▾」｜「图标大小」｜「新建文件夹」｜「清空素材」。
- **导入文件…**——选择文件导入（走 file input）。
- **▾ 下拉菜单**——三项：粘贴 SVG 代码 / GitHub 导入… / 导入 zip…。「粘贴 SVG 代码」与「GitHub 导入…」点击后弹出**居中文本输入框模态**（确定即导入）：SVG 是多行文本框，GitHub 是仓库地址 + 导入上限（0 = 不限）。
- **图标大小**——点击在按钮下方展开浮窗（滑块 + 数字输入框，0.6–1.6，默认 1），实时缩放素材网格里**文件夹卡与素材卡**的尺寸（列宽与卡片高度按倍率计算）；点击浮窗外部即收起，倍率写入本地存储（键 `dsh-gift-icon-scale-v1`），刷新/重启后保持。
- **卡片密度自适应**——素材以网格卡片铺开，每行数量随中栏宽度自动增减（窄屏更少、宽屏更多），卡片填满格宽。
- **循环缩略图**——SVG 缩略图每个共享 tick（3 秒）重挂一次，让一次性 CSS 动画循环重播、不再停在空白；动图（gif/apng/webp）本身就会循环，保持静态 `<img>`（不再周期性重解码）；png/jpg 保持静态，SVGA 用类型徽标 + 悬停预览。
- **卡权重 = 触发概率**——每张卡的「权重」（0–100）就是它在加权抽签里的概率系数；权重 0 表示永不触发。

支持的扩展名：`.svg`、`.svga`、`.gif`、`.apng`、`.webp`、`.png`、`.jpg`。单文件大小上限 `giftMaxAssetMB`（默认 8 MB，可调 1–64）。导入是**任务制**：上传接口返回任务对象，前端轮询 `/api/danmaku/gift/assets/import/status` 显示进度。素材文件落在 `$DSH_HOME/danmaku-gifts/files/`，清单为同目录 `manifest.json`；服务走 `GET /api/danmaku/gift/file?id=`（支持 Range / ETag / immutable 缓存）。

> [!NOTE]
> 礼物素材是**用户资产**：卸载插件时不会自动删除；「清空素材」按钮需二次确认。

左列礼物行的状态**只由素材库派生**：某礼物存在 `source === 'gift:<id>'` 的素材卡时显示**红色「×」**，否则显示**「+」**。点「+」→ Host 走白名单抓取（`importGift`）导入该礼物动画为一张卡，成功即变「×」；点「×」删除对应素材卡，该行**回落为「+」**（无二次确认）。没有素材卡的礼物在**库外不会触发**——抽签只从**素材库**里「有卡且有正权重」的素材中选。

## 礼物目录与房间号提取

礼物清单默认读 `$DSH_HOME/danmaku-gifts/catalog.json`；不存在时从包内 `assets/gift-catalog.json` 播种一份（离线可用）。

要**用自己的房间**礼物清单合并进目录：

1. 在中栏工具条的房间号输入框填号——**房间号由你本人填写**，仓库与文档里一律用占位符，例如 `<你的房间号>`。
2. 点「提取」。空输入 → 只弹提示、**不发任何请求**。

行为约定：

- 提取 = **合并去重**：把实时礼物配置映射后**并入当前目录**（保留已有条目，新增缺失的），而非整体替换；响应回 `{added, skipped}`，二次点击同一房间号 `added` 为 0。
- 提取成功 → 弹「新增 X / 跳过 Y」并刷新左列；失败 → 只弹 toast，**不写文件**、不回显房间号。
- 映射只读白名单字段，原始响应里的房间标识（`room_id` / `uid` 等）**不会**进入清单，也不会进日志（日志只打印数量摘要）。

## 礼物库：搜索 + 单分类下拉

左栏顶部一行是两个控件：**搜索框在左**（按名称 / ID 过滤，占满剩余宽度），**分类下拉在右**。下拉按钮显示当前选择 + 「▾」（如 `bilibili ▾` / `金瓜子 ▾` / `自定义 ▾`），点击展开**同一个浮窗**，父子两级都在里面：

- **bilibili**——顶层项，代表整个 bilibili 来源；其下按目录中首次出现顺序列出瓜子类型（金瓜子 / 银瓜子），点某一子项只显示该瓜子类型。
- **自定义**——叶子项，没有子级；列出素材库里非礼物来源的素材。

选中任一项后浮窗关闭、列表立即刷新（翻页回到第一页）；点击浮窗外部也会收起。浮窗向下展开、右对齐到下拉控件，不会横出左栏。不再有悬停展开的子菜单，也没有 `<select>` 或「类型 N」文案。

自定义行只有红色 **×**（删除素材，与卡上「×」同一接口）。自定义素材**入库即可被抽到**——不需要绑定到任何礼物；触发时用素材自己的名称。

## 特效位置

在**中栏点击一张素材卡**，右栏「特效位置」段显示它。位置是**素材自己的属性**，所以**任何**素材卡都能定位——来自礼物的（`source === 'gift:<id>'`）、直接上传的自定义素材、以及内置 SVG，无需先绑定任何礼物：

- **位置**——`center` / `top` / `bottom` / `top-left` / `top-right` / `bottom-left` / `bottom-right` / `left-mid` / `right-mid` / `custom` / `random` 共 11 个选项（10 个预设点位 + 随机）。
- **位置预览条**——小画框按归一化锚点显示落点，随下拉实时变化；**圆点可拖动**，拖动即写入**自定义**坐标（`x` / `y`，相对预览框归一化 0–1）。选任何预设都会覆盖自定义坐标。
- `random` 只从**显式白名单**的 9 个预设锚点里抽取（`custom` 与 `random` 本身都排除——随机抽取没有 x/y 可回退）。

**怎么退出选中态**：点中栏网格的**空白处**（没命中任何卡片）即取消选中，「特效位置」段回到**「选择一张素材以设置位置」**提示；关闭再打开礼物模态同样是空选中态。点卡片内部的元素（缩略图 / 名称 / 权重行 / 「×」）仍算选中该卡，不清空。

点左列礼物行**不再**弹出位置面板（行上只有「+」/「×」）。位置**写在素材清单上**（不再写在礼物绑定里），改动只做**增量**提交：`POST /api/danmaku/gift/assets {action:'position', id, position, x?, y?}`。`position:"custom"` 时另带 `x` / `y`（0–1，裁剪到 0–1、缺省 0.5），选任何预设都会丢弃这两个值。

## 基础与测试

右栏「基础」与「测试」两段（礼物总开关关闭时提示「先开启礼物模块」并禁用测试按钮），配置项逐行排列：

- **总概率**（`probability`，0–1）——礼物总开关打开后，按此概率与下面的最小/最大间隔参与抽签。**礼物总开关打开即随机触发**，没有单独的「随机环境触发」开关。
- **全局大小**（`giftScale`，0.25–3，默认 1）——所有礼物特效的统一倍率；与素材局部倍率相乘后决定特效尺寸（基准 = 视口短边 × 0.34）。
- **当前素材大小**（素材的 `scale`，0.25–3，默认 1）——选中一张素材卡后才可拖动（未选中时滑块禁用）；只影响该素材播放时的尺寸，写入素材清单。
- **最小间隔 / 最大间隔**——各占一行，均可拖动滑块，也可在右侧**数字输入框**直接填写（单位秒，1–3600）。
- **提示模板**（`giftTemplate`）——占位符 `{user}` 送礼人、`{gift}` 礼物名，最长 100 字符，输入时实时预览替换结果。
- **送礼人池**（`giftSenders`）——`{name, weight}` 加权列表，最多 50 条、名字最长 24 字符、权重 0–100；为空时用匿名。
- **立即测试**——立刻随机触发一次，并显示最近一次触发状态（礼物 / 送礼人 / 是否出错）；没有可触发素材时给出「没有可触发的礼物素材（先点左侧「+」添加）」提示。

> [!NOTE]
> 「手动触发」复选框已从界面移除；`giftTrigger.manual` **字段仍存在**于 schema 与默认值中（默认开），只是不再有对应控件。

触发时的行为：播放该素材的特效，并按 `giftTemplate` 叠加一条提示弹幕（`giftShowSender` 控制是否带昵称标签）；并发上限 `giftMaxConcurrent`（**默认 1**，1–10），超出排队，队列满则丢弃。随机触发**仅在「启用弹幕」与「启用礼物特效」都开启且有活跃会话时**参与，空白/无会话页不触发。

> [!NOTE]
> **关闭「启用弹幕」= 关闭插件**——总开关（`enabled`）关闭后，插件不再触发任何内容：任何类型的弹幕、礼物特效、礼物提示都不会出现，正在播放或排队的礼物动画会被**立即删除**；`giftEnabled` 仍是礼物模块自身的闸门（关闭时礼物模块零动作）。总开关开启时，礼物提示弹幕仍豁免 `maxOnscreen` 环境软上限（走 `renderer.spawnGift`）。特效还**只在真正上屏之后**才发提示弹幕（素材损坏或缺失时不发），且渲染器重建空窗期内发出的提示会先入队（有界，新胜旧），新渲染器挂载后再 flush（flush 时重新检查两个开关），不会在空窗里丢单。

## 隐私

- **房间号只存在本地**：`giftRoomId` 仅用于拼 `giftConfig(pc)` 请求，仓库（代码/脚本/CI/文档/测试/截图）里**从不出现真实房间号**，文档示例一律用占位符。
- 目录映射只读白名单字段，原始响应里的房间标识不会外泄；日志只打印数量摘要，不打印房间号。
- 房间号为空时不发起外部请求（见「礼物目录与房间号提取」）。
- `tools/check-gift-privacy.mjs` 是硬门：默认跑无需秘密的 agent 侧断言；最终门由用户以 `PRIVATE_ROOM_ID=<号码> node tools/check-gift-privacy.mjs` 传入真实号码，要求发布白名单内**零命中**。

## 限制

- **无音效**——特效只有画面，不播放声音。
- **无连击**——目录里的 `combo_id` 仅作为字段保留，没有连击 UI 或连击行为。
- **无移动端**——为桌面 Web 覆盖层设计（Chromium 优先），不做移动端布局。
- SVGA 依赖随包的播放器；素材只做视觉播放，不合成音频。